speedy-utils 1.1.23__tar.gz → 1.1.25__tar.gz

speedy_utils-1.1.25/IMPROVEMENTS.md

@@ -0,0 +1,141 @@
+# Multi-thread Error Tracing Improvements
+
+## Summary
+
+Significantly improved error tracing in `multi_thread` to focus on user code rather than infrastructure frames, making debugging much faster and easier.
+
+## Problem
+
+Previously, when errors occurred in functions executed by `multi_thread`, the traceback was cluttered with infrastructure frames:
+
+- `concurrent.futures` internals
+- `threading.py` frames
+- `multi_worker/thread.py` infrastructure code
+
+This made it difficult to quickly identify the actual problem in user code.
+
+### Example of OLD behavior:
+
+```
+TypeError                                 Traceback (most recent call last)
+Cell In[810], line 35
+     33     choices = multi_thread(fns, range(n))
+     34     return choices
+---> 35 choices = translate()
+
+File ~/projects/speedy_utils/src/speedy_utils/multi_worker/thread.py:474, in multi_thread(...)
+    472 idx, logical_size = _future_meta(fut)
+    473 try:
+--> 474     result = fut.result()
+    475 except Exception as exc:
+    476     if stop_on_error:
+
+File ~/.local/share/uv/python/.../concurrent/futures/_base.py:449, in Future.result(...)
+    447     raise CancelledError()
+    448 elif self._state == FINISHED:
+--> 449     return self.__get_result()
+
+... (many more infrastructure frames) ...
+
+TypeError: 'list' object is not callable
+```
+
+## Solution
+
+### 1. Added `UserFunctionError` Exception Class
+
+A custom exception wrapper that:
+
+- Captures the original exception
+- Stores the function name and input that caused the error
+- Filters traceback to include only user code frames
+- Provides clear, focused error messages
+
+### 2. Enhanced `_worker` Function
+
+- Added validation to detect common mistakes (e.g., passing a list instead of a function)
+- Filters tracebacks to remove infrastructure frames
+- Wraps user function errors in `UserFunctionError` with clean context
+- Provides helpful hints for common mistakes
+
+### 3. Improved Error Reporting in `multi_thread`
+
+- Logs clear error messages showing function name and input
+- Displays only user code in tracebacks
+- Re-raises exceptions with cleaned messages
+- Maintains proper exception chaining while hiding infrastructure noise
+
+## Benefits
+
+### Clear Error Messages
+
+```
+Error in function "process_item" with input: 0
+
+User code traceback:
+  File "your_script.py", line 20, in process_item
+    return my_list(x)
+           ^^^^^^^^^^
+TypeError: 'list' object is not callable
+```
+
+### Helpful Hints
+
+```
+TypeError:
+multi_thread: func parameter must be callable, got list: [...]
+Hint: Did you accidentally pass a list instead of a function?
+```
+
+### Nested Function Support
+
+Shows complete call chain through user code:
+
+```
+Error in function "process_data" with input: 0
+
+User code traceback:
+  File "your_script.py", line 44, in process_data
+    return validate_and_calc(val)
+           ^^^^^^^^^^^^^^^^^^^^^^
+  File "your_script.py", line 42, in validate_and_calc
+    return 100 / x
+           ~~~~^~~
+ZeroDivisionError: division by zero
+```
+
+## Key Improvements
+
+✅ **Errors show function name and problematic input**
+✅ **Tracebacks filtered to show only user code**
+✅ **No concurrent.futures/threading clutter**
+✅ **Helpful hints for common mistakes**
+✅ **Clear, actionable error messages**
+✅ **Maintains backward compatibility - all existing tests pass**
+
+## Testing
+
+Run the comprehensive demo to see all improvements:
+
+```bash
+python tests/test_multithread_error_trace.py
+```
+
+This demonstrates:
+
+1. Simple function errors
+2. Nested function call traces
+3. Common parameter type mistakes
+4. Various exception types (TypeError, ValueError, AttributeError, etc.)
+
+## Code Changes
+
+Main files modified:
+
+- `src/speedy_utils/multi_worker/thread.py`:
+  - Added `UserFunctionError` exception class
+  - Enhanced `_worker` function with validation and error filtering
+  - Improved error handling in `multi_thread` main loop
+  - Added imports for `sys` and `traceback`
+
+All changes maintain backward compatibility - existing code continues to work unchanged.

{speedy_utils-1.1.23 → speedy_utils-1.1.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: speedy-utils
-Version: 1.1.23
+Version: 1.1.25
 Summary: Fast and easy-to-use package for data science
 Project-URL: Homepage, https://github.com/anhvth/speedy
 Project-URL: Repository, https://github.com/anhvth/speedy

speedy_utils-1.1.25/debug_imemoize.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+Debug the imemoize cache key generation
+"""
+
+import sys
+import time
+import os.path as osp
+sys.path.insert(0, osp.join(osp.dirname(__file__), 'src'))
+
+from speedy_utils.common.utils_cache import imemoize, _GLOBAL_MEMORY_CACHE, get_source, identify, _compute_cache_components
+
+def debug_cache_keys():
+    """Debug what cache keys are generated"""
+    print("=== Debugging cache key generation ===")
+    
+    # Clear cache
+    _GLOBAL_MEMORY_CACHE.clear()
+    
+    # First function
+    @imemoize
+    def test_func(x):
+        return x * x
+    
+    # Get cache components
+    func_source1, sub_dir1, key_id1 = _compute_cache_components(
+        test_func, (5,), {}, True, None, None
+    )
+    cache_key1 = identify((func_source1, sub_dir1, key_id1))
+    
+    print(f"Function 1 source length: {len(func_source1)}")
+    print(f"Function 1 source: {func_source1[:100]}...")
+    print(f"Function 1 cache key: {cache_key1}")
+    
+    # Call function
+    result1 = test_func(5)
+    print(f"After call 1, cache size: {len(_GLOBAL_MEMORY_CACHE)}")
+    
+    # Redefine same function 
+    @imemoize
+    def test_func(x):
+        return x * x
+    
+    # Get cache components for redefined function
+    func_source2, sub_dir2, key_id2 = _compute_cache_components(
+        test_func, (5,), {}, True, None, None
+    )
+    cache_key2 = identify((func_source2, sub_dir2, key_id2))
+    
+    print(f"\nFunction 2 source length: {len(func_source2)}")
+    print(f"Function 2 source: {func_source2[:100]}...")
+    print(f"Function 2 cache key: {cache_key2}")
+    
+    print(f"\nSource code same: {func_source1 == func_source2}")
+    print(f"Cache keys same: {cache_key1 == cache_key2}")
+    
+    # Call function again
+    result2 = test_func(5)
+    print(f"After call 2, cache size: {len(_GLOBAL_MEMORY_CACHE)}")
+    
+    print(f"\nCache contents:")
+    for i, (key, value) in enumerate(_GLOBAL_MEMORY_CACHE.items()):
+        print(f"  {i+1}. {key[:50]}... -> {value}")
+
+if __name__ == "__main__":
+    debug_cache_keys()

speedy_utils-1.1.25/debug_imemoize_flow.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Debug the imemoize execution flow
+"""
+
+import sys
+import time
+import os.path as osp
+sys.path.insert(0, osp.join(osp.dirname(__file__), 'src'))
+
+from speedy_utils.common.utils_cache import _GLOBAL_MEMORY_CACHE, identify, _compute_cache_components
+from speedy_utils.common.utils_cache import mem_lock
+
+def create_debug_imemoize():
+    """Create a debug version of imemoize with detailed logging"""
+    import functools
+    import inspect
+    
+    def debug_imemoize(func):
+        print(f"Creating imemoize wrapper for {func.__name__}")
+        
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            print(f"\n--- Calling {func.__name__}({args}, {kwargs}) ---")
+            
+            # Compute cache key
+            func_source, sub_dir, key_id = _compute_cache_components(
+                func, args, kwargs, True, None, None
+            )
+            cache_key = identify((func_source, sub_dir, key_id))
+            
+            print(f"Function source: {func_source[:50]}...")
+            print(f"Cache key: {cache_key}")
+            print(f"Cache size before lookup: {len(_GLOBAL_MEMORY_CACHE)}")
+            
+            # Check cache
+            with mem_lock:
+                if cache_key in _GLOBAL_MEMORY_CACHE:
+                    cached_result = _GLOBAL_MEMORY_CACHE[cache_key]
+                    print(f"CACHE HIT: Found {cached_result}")
+                    return cached_result
+                else:
+                    print(f"CACHE MISS: Key not found")
+                    print(f"Available keys:")
+                    for i, key in enumerate(_GLOBAL_MEMORY_CACHE.keys()):
+                        print(f"  {i+1}. {key}")
+            
+            # Compute result
+            print(f"Computing result...")
+            start = time.time()
+            result = func(*args, **kwargs)
+            end = time.time()
+            print(f"Computation took {end - start:.6f}s")
+            
+            # Store in cache
+            with mem_lock:
+                _GLOBAL_MEMORY_CACHE[cache_key] = result
+                print(f"Stored result in cache. Cache size now: {len(_GLOBAL_MEMORY_CACHE)}")
+            
+            return result
+        
+        return wrapper
+    
+    return debug_imemoize
+
+def test_debug():
+    debug_imemoize = create_debug_imemoize()
+    
+    # Clear cache
+    _GLOBAL_MEMORY_CACHE.clear()
+    print("Cache cleared")
+    
+    # First function
+    @debug_imemoize
+    def test_func(x):
+        time.sleep(0.05)
+        return x * x
+    
+    print("\n=== FIRST CALL ===")
+    result1 = test_func(5)
+    
+    print("\n=== SECOND CALL (same function object) ===")
+    result2 = test_func(5)
+    
+    # Redefine function
+    @debug_imemoize
+    def test_func(x):
+        time.sleep(0.05) 
+        return x * x
+    
+    print("\n=== THIRD CALL (new function object, same source) ===")
+    result3 = test_func(5)
+
+if __name__ == "__main__":
+    test_debug()

speedy_utils-1.1.25/examples/temperature_range_example.py

@@ -0,0 +1,119 @@
+"""Example demonstrating temperature range sampling with LLM."""
+
+from llm_utils import LLM
+from pydantic import BaseModel
+
+
+class CreativeStory(BaseModel):
+    """A creative story output."""
+
+    title: str
+    story: str
+    moral: str
+
+
+def example_temperature_range_text():
+    """Example: Sample text responses with different temperatures."""
+    print("=" * 60)
+    print("Example 1: Temperature Range Sampling (Text Completion)")
+    print("=" * 60)
+
+    llm = LLM(
+        instruction="You are a creative writer. Write a very short story.",
+        output_model=str,
+    )
+
+    prompt = "Write a one-sentence story about a brave mouse."
+
+    # Sample with 5 different temperatures from 0.1 to 1.0
+    responses = llm(
+        prompt,
+        temperature_ranges=(0.1, 1.0),
+        n=5,
+    )
+
+    print(f"\nGenerated {len(responses)} responses with varying temperatures:\n")
+    for i, resp in enumerate(responses):
+        temp = 0.1 + i * ((1.0 - 0.1) / (5 - 1))
+        print(f"Temperature ~{temp:.2f}:")
+        print(f"  {resp['parsed']}\n")
+
+
+def example_temperature_range_pydantic():
+    """Example: Sample structured responses with different temperatures."""
+    print("=" * 60)
+    print("Example 2: Temperature Range with Pydantic Models")
+    print("=" * 60)
+
+    llm = LLM(
+        instruction="Create a creative short story with a moral lesson.",
+        output_model=CreativeStory,
+    )
+
+    prompt = "Topic: A robot learning to feel emotions"
+
+    # Sample with 3 different temperatures from 0.5 to 1.5
+    responses = llm(
+        prompt,
+        temperature_ranges=(0.5, 1.5),
+        n=3,
+    )
+
+    print(f"\nGenerated {len(responses)} stories with varying creativity:\n")
+    for i, resp in enumerate(responses):
+        temp = 0.5 + i * ((1.5 - 0.5) / (3 - 1))
+        story = resp["parsed"]
+        print(f"Temperature ~{temp:.2f}:")
+        print(f"  Title: {story.title}")
+        print(f"  Story: {story.story[:80]}...")
+        print(f"  Moral: {story.moral}\n")
+
+
+def example_two_step_parsing():
+    """Example: Two-step Pydantic parsing for models with reasoning."""
+    print("=" * 60)
+    print("Example 3: Two-Step Pydantic Parsing")
+    print("=" * 60)
+
+    llm = LLM(
+        instruction=("Analyze the given text and extract structured information. Think through your analysis first."),
+        output_model=CreativeStory,
+    )
+
+    prompt = "Analyze the story: 'The tortoise won the race by persistence.'"
+
+    # Use two-step parsing (useful for reasoning models)
+    response = llm(
+        prompt,
+        two_step_parse_pydantic=True,
+    )[0]
+
+    story = response["parsed"]
+    print("\nExtracted structure:")
+    print(f"  Title: {story.title}")
+    print(f"  Story: {story.story}")
+    print(f"  Moral: {story.moral}")
+
+
+if __name__ == "__main__":
+    # Run examples
+    # Note: These require a working OpenAI API key or local LLM server
+
+    try:
+        example_temperature_range_text()
+    except Exception as e:
+        print(f"Example 1 failed: {e}\n")
+
+    try:
+        example_temperature_range_pydantic()
+    except Exception as e:
+        print(f"Example 2 failed: {e}\n")
+
+    try:
+        example_two_step_parsing()
+    except Exception as e:
+        print(f"Example 3 failed: {e}\n")
+
+    print("\n" + "=" * 60)
+    print("Examples complete!")
+    print("=" * 60)

speedy_utils-1.1.25/examples_improved_error_tracing.py

@@ -0,0 +1,85 @@
+"""
+Direct comparison: Before and After error tracing improvements.
+
+This demonstrates the exact improvement for the user's original error case.
+"""
+
+from speedy_utils import multi_thread
+
+
+def simulate_original_error():
+    """
+    Simulates the exact error from the user's example:
+    - User has a function that creates lambda functions
+    - Accidentally passes list of functions as 'func' parameter
+    - Gets TypeError: 'list' object is not callable
+    """
+    
+    def lm_translate(msgs, temperature, max_tokens):
+        """Mock language model translate function."""
+        return [{'parsed': f'translation at temp={temperature:.2f}'}]
+    
+    def translate(n=5, max_temperature=1.0):
+        """Function that generates choices with different temperatures."""
+        step = max_temperature / n
+        fns = []
+        target_text = 'Some text to translate'
+        msgs = [{'role': 'user', 'content': 'Translate this'}]
+        
+        for i in range(n):
+            fn = lambda x: lm_translate(
+                msgs,
+                temperature=0.1 + 0.1 * i * step,
+                max_tokens=len(target_text) + 32,
+            )[0]
+            fns.append(fn)
+        
+        # THE BUG: User passed fns (a list) as the func parameter
+        # Should be: multi_thread(some_function, fns)
+        # Instead did: multi_thread(fns, range(n))
+        choices = multi_thread(fns, range(n), progress=False)
+        return choices
+    
+    return translate()
+
+
+def main():
+    print('='*70)
+    print('BEFORE vs AFTER: Error Tracing Improvements')
+    print('='*70)
+    
+    print('\nBEFORE (old behavior):')
+    print('-' * 70)
+    print('''
+The error traceback showed:
+  - Line in multi_thread.py:474
+  - concurrent.futures/_base.py:449
+  - concurrent.futures/thread.py:59
+  - multi_worker/thread.py:155
+  - ... many infrastructure frames ...
+  - Finally: TypeError: 'list' object is not callable
+
+User had to dig through 10+ lines of infrastructure code
+to find the actual problem.
+''')
+    
+    print('\nAFTER (new behavior):')
+    print('-' * 70)
+    
+    try:
+        simulate_original_error()
+    except TypeError as e:
+        print(f'\n{type(e).__name__}: {e}\n')
+    
+    print('-' * 70)
+    print('\nKey differences:')
+    print('  ✓ Immediate identification of the problem')
+    print('  ✓ Clear hint about what went wrong')
+    print('  ✓ Shows exactly what was passed (list of functions)')
+    print('  ✓ No infrastructure clutter')
+    print('  ✓ Debugging time: < 5 seconds vs > 1 minute')
+    print('='*70)
+
+
+if __name__ == '__main__':
+    main()