speedy-utils 1.1.32__tar.gz → 1.1.34__tar.gz

speedy_utils-1.1.34/.github/skills/caching-utilities/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: 'caching-utilities'
+description: 'Guide for using caching utilities in speedy_utils, including memory, disk, and hybrid caching strategies for sync and async functions.'
+---
+
+# Caching Utilities Guide
+
+This skill provides comprehensive guidance for using the caching utilities in `speedy_utils`.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Optimize performance by caching expensive function calls.
+- Persist results across program runs using disk caching.
+- Use memory caching for fast access within a single run.
+- Handle caching for both synchronous and asynchronous functions.
+- Use `imemoize` for persistent caching in interactive environments like Jupyter notebooks.
+
+## Prerequisites
+
+- `speedy_utils` installed in your environment.
+
+## Core Capabilities
+
+### Universal Memoization (`@memoize`)
+- Supports `memory`, `disk`, and `both` (hybrid) caching backends.
+- Works with both `sync` and `async` functions.
+- Configurable LRU cache size for memory caching.
+- Custom key generation strategies.
+
+### Interactive Memoization (`@imemoize`)
+- Designed for Jupyter notebooks and interactive sessions.
+- Persists cache across module reloads (`%load`).
+- Uses global memory cache.
+
+### Object Identification (`identify`)
+- Generates stable, content-based identifiers for arbitrary Python objects.
+- Handles complex types like DataFrames, Pydantic models, and nested structures.
+
+## Usage Examples
+
+### Example 1: Basic Hybrid Caching
+Cache results in both memory and disk.
+
+```python
+from speedy_utils import memoize
+import time
+
+@memoize(cache_type='both', size=128)
+def expensive_func(x: int):
+    time.sleep(1)
+    return x * x
+```
+
+### Example 2: Async Disk Caching
+Cache results of an async function to disk.
+
+```python
+from speedy_utils import memoize
+import asyncio
+
+@memoize(cache_type='disk', cache_dir='./my_cache')
+async def fetch_data(url: str):
+    # simulate network call
+    await asyncio.sleep(1)
+    return {"data": "content"}
+```
+
+### Example 3: Custom Key Function
+Use a custom key function for complex arguments.
+
+```python
+from speedy_utils import memoize
+
+def get_user_id(user):
+    return user.id
+
+@memoize(key=get_user_id)
+def process_user(user):
+    # ...
+    pass
+```
+
+### Example 4: Interactive Caching (Notebooks)
+Use `@imemoize` to keep cache even if you reload the cell/module.
+
+```python
+from speedy_utils import imemoize
+
+@imemoize
+def notebook_func(data):
+    # ...
+    return result
+```
+
+## Guidelines
+
+1.  **Choose the Right Backend**:
+    - Use `memory` for small, fast results needed frequently in one session.
+    - Use `disk` for large results or to persist across runs.
+    - Use `both` (default) for the best of both worlds.
+
+2.  **Key Stability**:
+    - Ensure arguments are stable (e.g., avoid using objects with changing internal state as keys unless you provide a custom `key` function).
+    - `identify` handles most common types, but be careful with custom classes without `__repr__` or stable serialization.
+
+3.  **Cache Directory**:
+    - Default disk cache is `~/.cache/speedy_cache`.
+    - Override `cache_dir` for project-specific caching.
+
+4.  **Async Support**:
+    - The decorators automatically detect `async` functions and handle `await` correctly.
+    - Do not mix sync/async usage without proper `await`.
+
+## Common Patterns
+
+### Pattern: Ignoring `self`
+By default, `ignore_self=True` is set. This means methods on different instances of the same class will share cache if other arguments are the same. Set `ignore_self=False` if the instance state matters.
+
+```python
+class Processor:
+    def __init__(self, multiplier):
+        self.multiplier = multiplier
+
+    @memoize(ignore_self=False)
+    def compute(self, x):
+        return x * self.multiplier
+```
+
+## Limitations
+
+- **Pickle Compatibility**: Disk caching relies on `pickle` (or JSON). Ensure return values are serializable.
+- **Cache Invalidation**: There is no automatic TTL (Time To Live) or expiration. You must manually clear cache files if data becomes stale.

speedy_utils-1.1.34/.github/skills/caching-utilities/examples/caching_example.py

@@ -0,0 +1,37 @@
+import asyncio
+import time
+
+from speedy_utils import imemoize, memoize
+
+
+# Sync Hybrid Cache
+@memoize(cache_type='both')
+def slow_square(x: int) -> int:
+    print(f"Computing square of {x}...")
+    time.sleep(1)
+    return x * x
+
+# Async Disk Cache
+@memoize(cache_type='disk', cache_dir='./temp_cache')
+async def async_slow_cube(x: int) -> int:
+    print(f"Computing cube of {x}...")
+    await asyncio.sleep(1)
+    return x * x * x
+
+# Interactive Cache
+@imemoize
+def interactive_op(x: int) -> int:
+    print(f"Interactive op on {x}...")
+    return x + 1
+
+async def main():
+    print("--- Sync Cache ---")
+    print(slow_square(2))
+    print(slow_square(2)) # Should be instant
+
+    print("\n--- Async Cache ---")
+    print(await async_slow_cube(3))
+    print(await async_slow_cube(3)) # Should be instant
+
+if __name__ == "__main__":
+    asyncio.run(main())

speedy_utils-1.1.34/.github/skills/io-utilities/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: 'io-utilities'
+description: 'Guide for using IO utilities in speedy_utils, including fast JSONL reading, multi-format loading, and file serialization.'
+---
+
+# IO Utilities Guide
+
+This skill provides comprehensive guidance for using the IO utilities in `speedy_utils`.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Read and write data in various formats (JSON, JSONL, Pickle, CSV, TXT).
+- Efficiently process large JSONL files with streaming and multi-threading.
+- Automatically handle file compression (gzip, bz2, xz, zstd).
+- Load data based on file extension automatically.
+- Serialize Pydantic models and other objects easily.
+
+## Prerequisites
+
+- `speedy_utils` installed.
+- Optional dependencies for specific features:
+    - `orjson`: For faster JSON parsing.
+    - `zstandard`: For `.zst` file support.
+    - `pandas`: For CSV/TSV loading.
+    - `pyarrow`: For faster CSV reading with pandas.
+
+## Core Capabilities
+
+### Fast JSONL Processing (`fast_load_jsonl`)
+- Streams data line-by-line for memory efficiency.
+- Supports automatic decompression.
+- Uses `orjson` if available for speed.
+- Supports multi-threaded processing for large files.
+- Shows progress bar with `tqdm`.
+
+### Universal Loading (`load_by_ext`)
+- Detects file type by extension.
+- Supports glob patterns (e.g., `data/*.json`) and lists of files.
+- Uses parallel processing for multiple files.
+- Supports memoization via `do_memoize=True`.
+
+### Serialization (`dump_json_or_pickle`, `load_json_or_pickle`)
+- Unified interface for JSON and Pickle.
+- Handles Pydantic models automatically.
+- Creates parent directories if they don't exist.
+
+## Usage Examples
+
+### Example 1: Streaming Large JSONL
+Read a large compressed JSONL file line by line.
+
+```python
+from speedy_utils import fast_load_jsonl
+
+# Iterates lazily, low memory usage
+for item in fast_load_jsonl('large_data.jsonl.gz', progress=True):
+    process(item)
+```
+
+### Example 2: Loading Any File
+Load a file without worrying about the format.
+
+```python
+from speedy_utils import load_by_ext
+
+data = load_by_ext('config.json')
+df = load_by_ext('data.csv')
+items = load_by_ext('dataset.pkl')
+```
+
+### Example 3: Parallel Loading
+Load multiple files in parallel.
+
+```python
+from speedy_utils import load_by_ext
+
+# Returns a list of results, one for each file
+all_data = load_by_ext('logs/*.jsonl')
+```
+
+### Example 4: Dumping Data
+Save data to disk, creating directories as needed.
+
+```python
+from speedy_utils import dump_json_or_pickle
+
+data = {"key": "value"}
+dump_json_or_pickle(data, 'output/processed/result.json')
+```
+
+## Guidelines
+
+1.  **Prefer JSONL for Large Datasets**:
+    - Use `fast_load_jsonl` for datasets that don't fit in memory.
+    - It handles compression transparently, so keep files compressed (`.jsonl.gz` or `.jsonl.zst`) to save space.
+
+2.  **Use `load_by_ext` for Scripts**:
+    - When writing scripts that might accept different input formats, use `load_by_ext` to be flexible.
+
+3.  **Error Handling**:
+    - `fast_load_jsonl` has an `on_error` parameter (`raise`, `warn`, `skip`) to handle malformed lines gracefully.
+
+4.  **Performance**:
+    - Install `orjson` for significantly faster JSON operations.
+    - `load_by_ext` uses `pyarrow` engine for CSVs if available, which is much faster.
+
+## Limitations
+
+- **Memory Usage**: `load_by_ext` loads the entire file into memory. Use `fast_load_jsonl` for streaming.
+- **Glob Expansion**: `load_by_ext` with glob patterns loads *all* matching files into memory at once (in a list). Be careful with massive datasets.

speedy_utils-1.1.34/.github/skills/io-utilities/examples/io_example.py

@@ -0,0 +1,35 @@
+import os
+
+from speedy_utils import dump_json_or_pickle, fast_load_jsonl, load_by_ext
+
+
+def main():
+    # 1. Create some dummy data
+    data = [{"id": i, "value": f"item_{i}"} for i in range(100)]
+
+    # 2. Dump to JSONL
+    print("Dumping to data.jsonl...")
+    dump_json_or_pickle(data, 'data.jsonl')
+
+    # 3. Dump to Pickle
+    print("Dumping to data.pkl...")
+    dump_json_or_pickle(data, 'data.pkl')
+
+    # 4. Load using load_by_ext
+    print("Loading data.pkl...")
+    loaded_pkl = load_by_ext('data.pkl')
+    print(f"Loaded {len(loaded_pkl)} items from pickle.")
+
+    # 5. Stream using fast_load_jsonl
+    print("Streaming data.jsonl...")
+    count = 0
+    for item in fast_load_jsonl('data.jsonl', progress=True):
+        count += 1
+    print(f"Streamed {count} items from jsonl.")
+
+    # Cleanup
+    os.remove('data.jsonl')
+    os.remove('data.pkl')
+
+if __name__ == "__main__":
+    main()

speedy_utils-1.1.34/.github/skills/llm-integration/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: 'llm-integration'
+description: 'Guide for using LLM utilities in speedy_utils, including memoized OpenAI clients and chat format transformations.'
+---
+
+# LLM Integration Guide
+
+This skill provides comprehensive guidance for using the LLM utilities in `speedy_utils`.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Make OpenAI API calls with automatic caching (memoization) to save costs and time.
+- Transform chat messages between different formats (ChatML, ShareGPT, Text).
+- Prepare prompts for local LLM inference.
+
+## Prerequisites
+
+- `speedy_utils` installed.
+- `openai` package installed for API clients.
+
+## Core Capabilities
+
+### Memoized OpenAI Clients (`MOpenAI`, `MAsyncOpenAI`)
+- Drop-in replacements for `OpenAI` and `AsyncOpenAI`.
+- Automatically caches `post` (chat completion) requests.
+- Uses `speedy_utils` caching backend (disk/memory).
+- Configurable per-instance caching.
+
+### Chat Format Transformation (`transform_messages`)
+- Converts between:
+    - `chatml`: List of `{"role": "...", "content": "..."}` dicts.
+    - `sharegpt`: Dict with `{"conversations": [{"from": "...", "value": "..."}]}`.
+    - `text`: String with `<|im_start|>` tokens.
+    - `simulated_chat`: Human/AI transcript format.
+- Supports applying tokenizer templates.
+
+## Usage Examples
+
+### Example 1: Memoized OpenAI Call
+Make repeated calls without hitting the API twice.
+
+```python
+from llm_utils.lm.openai_memoize import MOpenAI
+
+# Initialize just like OpenAI client
+client = MOpenAI(api_key="sk-...")
+
+# First call hits the API
+response1 = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+# Second call returns cached result instantly
+response2 = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### Example 2: Async Memoized Call
+Same as above but for async workflows.
+
+```python
+from llm_utils.lm.openai_memoize import MAsyncOpenAI
+import asyncio
+
+async def main():
+    client = MAsyncOpenAI(api_key="sk-...")
+    response = await client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hi"}]
+    )
+```
+
+### Example 3: Transforming Chat Formats
+Convert ShareGPT format to ChatML.
+
+```python
+from llm_utils.chat_format.transform import transform_messages
+
+sharegpt_data = {
+    "conversations": [
+        {"from": "human", "value": "Hi"},
+        {"from": "gpt", "value": "Hello there"}
+    ]
+}
+
+# Convert to ChatML list
+chatml_data = transform_messages(sharegpt_data, frm="sharegpt", to="chatml")
+# Result: [{'role': 'user', 'content': 'Hi'}, {'role': 'assistant', 'content': 'Hello there'}]
+
+# Convert to Text string
+text_data = transform_messages(chatml_data, frm="chatml", to="text")
+# Result: "<|im_start|>user\nHi<|im_end|>\n<|im_start|>assistant\nHello there<|im_end|>\n<|im_start|>assistant\n"
+```
+
+## Guidelines
+
+1.  **Caching Behavior**:
+    - The cache key is generated from the arguments passed to `create`.
+    - If you change any parameter (e.g., `temperature`, `model`), it counts as a new request.
+    - Cache is persistent if configured (default behavior of `memoize`).
+
+2.  **Format Detection**:
+    - `transform_messages` tries to auto-detect input format, but it's safer to specify `frm` explicitly.
+
+3.  **Tokenizer Support**:
+    - You can pass a HuggingFace `tokenizer` to `transform_messages` to use its specific chat template.
+
+## Limitations
+
+- **Streaming**: Memoization does NOT work with streaming responses (`stream=True`).
+- **Side Effects**: If your LLM calls rely on randomness (high temperature) and you want different results each time, disable caching or change the seed/input.

speedy_utils-1.1.34/.github/skills/llm-integration/examples/llm_example.py

@@ -0,0 +1,27 @@
+from llm_utils.chat_format.transform import transform_messages
+
+
+def main():
+    # 1. Define ShareGPT data
+    sharegpt_data = {
+        "conversations": [
+            {"from": "human", "value": "What is the capital of France?"},
+            {"from": "gpt", "value": "The capital of France is Paris."}
+        ]
+    }
+    print("Original ShareGPT:", sharegpt_data)
+
+    # 2. Convert to ChatML
+    chatml_data = transform_messages(sharegpt_data, frm="sharegpt", to="chatml")
+    print("\nConverted to ChatML:", chatml_data)
+
+    # 3. Convert to Text (Prompt)
+    text_data = transform_messages(chatml_data, frm="chatml", to="text")
+    print("\nConverted to Text Prompt:\n", text_data)
+
+    # 4. Convert to Simulated Chat
+    sim_chat = transform_messages(chatml_data, frm="chatml", to="simulated_chat")
+    print("\nConverted to Simulated Chat:\n", sim_chat)
+
+if __name__ == "__main__":
+    main()