kash-shell 0.3.16__py3-none-any.whl → 0.3.18__py3-none-any.whl

kash/media_base/media_cache.py

@@ -3,6 +3,7 @@ from functools import cache
 from pathlib import Path
 
 from prettyfmt import fmt_lines, fmt_path
+from prettyfmt.prettyfmt import fmt_size_dual
 from strif import atomic_output_file
 
 from kash.config.logger import get_logger
@@ -14,6 +15,7 @@ from kash.media_base.media_services import (
 )
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, as_file_url, is_url
+from kash.utils.common.url_slice import parse_url_slice
 from kash.utils.errors import FileNotFound, InvalidInput, UnexpectedError
 from kash.utils.file_utils.file_formats_model import MediaType
 from kash.web_content.dir_store import DirStore
@@ -51,14 +53,16 @@ class MediaCache(DirStore):
         super().__init__(root)
 
     def _write_transcript(self, url: Url, content: str) -> None:
-        transcript_path = self.path_for(url, suffix=SUFFIX_TRANSCRIPT)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        transcript_path = self.path_for(key, suffix=SUFFIX_TRANSCRIPT)
         with atomic_output_file(transcript_path) as temp_output:
             with open(temp_output, "w") as f:
                 f.write(content)
         log.message("Transcript saved to cache: %s", fmt_path(transcript_path))
 
     def _read_transcript(self, url: Url) -> str | None:
-        transcript_file = self.find(url, suffix=SUFFIX_TRANSCRIPT)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        transcript_file = self.find(key, suffix=SUFFIX_TRANSCRIPT)
         if transcript_file:
             log.message("Video transcript already in cache: %s: %s", url, fmt_path(transcript_file))
             with open(transcript_file) as f:
@@ -66,12 +70,13 @@ class MediaCache(DirStore):
         return None
 
     def _downsample_audio(self, url: Url) -> Path:
-        downsampled_audio_file = self.find(url, suffix=SUFFIX_16KMP3)
+        key = str(url)  # Cache key is the URL (with slice fragment if present)
+        downsampled_audio_file = self.find(key, suffix=SUFFIX_16KMP3)
         if not downsampled_audio_file:
-            full_audio_file = self.find(url, suffix=SUFFIX_MP3)
+            full_audio_file = self.find(key, suffix=SUFFIX_MP3)
             if not full_audio_file:
                 raise ValueError("No audio file found for: %s" % url)
-            downsampled_audio_file = self.path_for(url, suffix=SUFFIX_16KMP3)
+            downsampled_audio_file = self.path_for(key, suffix=SUFFIX_16KMP3)
             log.message(
                 "Downsampling audio: %s -> %s",
                 fmt_path(full_audio_file),
@@ -95,13 +100,18 @@ class MediaCache(DirStore):
         return transcript
 
     def cache(
-        self, url: Url, refetch=False, media_types: list[MediaType] | None = None
+        self, url_or_slice: Url, refetch=False, media_types: list[MediaType] | None = None
     ) -> dict[MediaType, Path]:
         """
         Cache the media files for the given media URL. Returns paths to cached copies
         for each media type (video or audio). Returns cached copies if available,
         unless `refetch` is True.
         """
+        key = str(url_or_slice)  # Cache key is the URL (with slice fragment if present)
+
+        # Extract base URL and slice information
+        base_url, slice = parse_url_slice(url_or_slice)
+
         cached_paths: dict[MediaType, Path] = {}
 
         if not media_types:
@@ -109,14 +119,18 @@ class MediaCache(DirStore):
 
         if not refetch:
             if MediaType.audio in media_types:
-                audio_file = self.find(url, suffix=SUFFIX_MP3)
+                audio_file = self.find(key, suffix=SUFFIX_MP3)
                 if audio_file:
-                    log.message("Audio already in cache: %s: %s", url, fmt_path(audio_file))
+                    log.message(
+                        "Audio already in cache: %s: %s", url_or_slice, fmt_path(audio_file)
+                    )
                     cached_paths[MediaType.audio] = audio_file
             if MediaType.video in media_types:
-                video_file = self.find(url, suffix=SUFFIX_MP4)
+                video_file = self.find(key, suffix=SUFFIX_MP4)
                 if video_file:
-                    log.message("Video already in cache: %s: %s", url, fmt_path(video_file))
+                    log.message(
+                        "Video already in cache: %s: %s", url_or_slice, fmt_path(video_file)
+                    )
                     cached_paths[MediaType.video] = video_file
             if set(media_types).issubset(cached_paths.keys()):
                 return cached_paths
@@ -127,23 +141,30 @@ class MediaCache(DirStore):
                     [t.name for t in cached_paths.keys()],
                 )
 
-        log.message("Downloading media: %s", url)
-        media_paths = download_media_by_service(url, self.root, media_types)
+        log.message("Downloading media: %s", url_or_slice)
+        media_paths = download_media_by_service(
+            base_url, self.root, media_types=media_types, slice=slice
+        )
         if MediaType.audio in media_paths:
-            audio_path = self.path_for(url, suffix=SUFFIX_MP3)
+            audio_path = self.path_for(key, suffix=SUFFIX_MP3)
             os.rename(media_paths[MediaType.audio], audio_path)
             cached_paths[MediaType.audio] = audio_path
         if MediaType.video in media_paths:
-            video_path = self.path_for(url, suffix=SUFFIX_MP4)
+            video_path = self.path_for(key, suffix=SUFFIX_MP4)
             os.rename(media_paths[MediaType.video], video_path)
             cached_paths[MediaType.video] = video_path
 
         log.message(
             "Downloaded media and saved to cache:\n%s",
-            fmt_lines([f"{t.name}: {fmt_path(p)}" for (t, p) in cached_paths.items()]),
+            fmt_lines(
+                [
+                    f"{t.name}: {fmt_size_dual(p.stat().st_size)}: {fmt_path(p)} "
+                    for (t, p) in cached_paths.items()
+                ]
+            ),
         )
 
-        self._downsample_audio(url)
+        self._downsample_audio(url_or_slice)
 
         return cached_paths
 
@@ -156,30 +177,33 @@ class MediaCache(DirStore):
         """
         if not isinstance(url_or_path, Path) and is_url(url_or_path):
             # If it is a URL, cache it locally.
-            url = url_or_path
-            url = canonicalize_media_url(url)
-            if not url:
+            url_or_slice = url_or_path
+            # Canonicalize the URL (preserving slice information if present)
+            canon = canonicalize_media_url(url_or_slice)
+            if not canon:
                 log.error("Unrecognized media, current services: %s", get_media_services())
                 raise InvalidInput(
                     "Unrecognized media URL (is this media service configured?): %s" % url_or_path
                 )
+            url_or_slice = canon
+
             if not refetch:
-                transcript = self._read_transcript(url)
+                transcript = self._read_transcript(url_or_slice)
                 if transcript:
                     return transcript
             # Cache all formats since we usually will want them.
-            self.cache(url, refetch)
+            self.cache(url_or_slice, refetch)
         elif isinstance(url_or_path, Path):
             # Treat local media files as file:// URLs.
             # Don't need to cache originals but we still will cache audio and transcriptions.
             if not url_or_path.exists():
                 raise FileNotFound(f"File not found: {fmt_loc(url_or_path)}")
-            url = as_file_url(url_or_path)
+            url_or_slice = as_file_url(url_or_path)
         else:
             raise InvalidInput(f"Not a media URL or path: {fmt_loc(url_or_path)}")
 
         # Now do the transcription.
-        transcript = self._do_transcription(url, language=language)
+        transcript = self._do_transcription(url_or_slice, language=language)
         if not transcript:
-            raise UnexpectedError("No transcript found for: %s" % url)
+            raise UnexpectedError("No transcript found for: %s" % url_or_slice)
         return transcript

kash/media_base/media_services.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 from pathlib import Path
 
@@ -7,6 +9,7 @@ from strif import AtomicVar
 from kash.media_base.services.local_file_media import LocalFileMedia
 from kash.model.media_model import MediaMetadata, MediaService
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice, add_slice_to_url, parse_url_slice
 from kash.utils.errors import InvalidInput
 from kash.utils.file_utils.file_formats_model import MediaType
 
@@ -32,14 +35,22 @@ def register_media_service(*services: MediaService) -> None:
     _media_services.update(lambda services: services + new_services)
 
 
-def canonicalize_media_url(url: Url) -> Url | None:
+def canonicalize_media_url(url_or_slice: Url) -> Url | None:
     """
     Return the canonical form of a media URL from a supported service (like YouTube).
+    Preserves any slice information in URL fragments.
     """
+    base_url, slice = parse_url_slice(url_or_slice)
+
+    # Canonicalize the base URL
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return canonical_url
+            # Add slice back to canonical URL if it existed
+            if slice:
+                return add_slice_to_url(canonical_url, slice)
+            else:
+                return canonical_url
     return None
 
 
@@ -51,10 +62,11 @@ def thumbnail_media_url(url: Url) -> Url | None:
     """
     Return a URL that links to the thumbnail of the media.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.thumbnail_url(url)
+            return service.thumbnail_url(base_url)
     return None
 
 
@@ -62,18 +74,21 @@ def timestamp_media_url(url: Url, timestamp: float) -> Url:
     """
     Return a URL that links to the media at the given timestamp.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.timestamp_url(url, timestamp)
+            return service.timestamp_url(base_url, timestamp)
     raise InvalidInput(f"Unrecognized media URL: {url}")
 
 
 def get_media_id(url: Url | None) -> str | None:
     if not url:
         return None
+
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        media_id = service.get_media_id(url)
+        media_id = service.get_media_id(base_url)
         if media_id:
             return media_id
     return None
@@ -84,10 +99,11 @@ def get_media_metadata(url: Url) -> MediaMetadata | None:
     """
     Return metadata for the media at the given URL.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        media_id = service.get_media_id(url)
+        media_id = service.get_media_id(base_url)
         if media_id:  # This is an actual video, not a channel etc.
-            return service.metadata(url)
+            return service.metadata(base_url)
     return None
 
 
@@ -95,18 +111,51 @@ def list_channel_items(url: Url) -> list[MediaMetadata]:
     """
     List all items in a channel.
     """
+    base_url, _ = parse_url_slice(url)
     for service in _media_services.copy():
-        canonical_url = service.canonicalize(url)
+        canonical_url = service.canonicalize(base_url)
         if canonical_url:
-            return service.list_channel_items(url)
+            return service.list_channel_items(base_url)
     raise InvalidInput(f"Unrecognized media URL: {url}")
 
 
 def download_media_by_service(
-    url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+    url: Url,
+    target_dir: Path,
+    *,
+    media_types: list[MediaType] | None = None,
+    slice: Slice | None = None,
 ) -> dict[MediaType, Path]:
     for service in _media_services.copy():
         canonical_url = service.canonicalize(url)
         if canonical_url:
-            return service.download_media(url, target_dir, media_types=media_types)
+            return service.download_media(url, target_dir, media_types=media_types, slice=slice)
     raise ValueError(f"Unrecognized media URL: {url}")
+
+
+## Tests
+
+
+def test_canonicalize_media_url_preserves_slice():
+    """Test that canonicalize_media_url preserves URL slice fragments."""
+
+    # Test with unrecognized URLs (should return None)
+    # This tests the slice extraction/reconstruction logic without requiring actual files
+    unrecognized_url = Url("https://unknown-service.com/video#~slice=10-30")
+    canonical_unknown = canonicalize_media_url(unrecognized_url)
+    assert canonical_unknown is None
+
+    # Test typical YouTube URL with slice (would work if YouTube service was registered)
+    youtube_url = Url("https://www.youtube.com/watch?v=dQw4w9WgXcQ#~slice=10-30")
+    # For now this returns None since YouTube service isn't registered in this test
+    # but the slice extraction/reconstruction logic is tested in url_slice.py
+    youtube_canonical = canonicalize_media_url(youtube_url)
+    assert youtube_canonical is None  # No YouTube service registered
+
+    # Test HH:MM:SS format slice
+    hms_youtube_url = Url("https://www.youtube.com/watch?v=dQw4w9WgXcQ#~slice=01:30-02:45")
+    canonical_hms = canonicalize_media_url(hms_youtube_url)
+    assert canonical_hms is None  # No YouTube service registered
+
+    # The actual slice functionality is thoroughly tested in url_slice.py
+    # This test ensures canonicalize_media_url doesn't break with slice URLs

kash/media_base/services/local_file_media.py

@@ -13,6 +13,7 @@ from kash.file_storage.store_filenames import parse_item_filename
 from kash.model.media_model import MediaMetadata, MediaService, MediaUrlType
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice
 from kash.utils.errors import FileNotFound, InvalidInput
 from kash.utils.file_utils.file_formats_model import FileExt, MediaType
 
@@ -73,11 +74,18 @@ class LocalFileMedia(MediaService):
 
     @override
     def download_media(
-        self, url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+        self,
+        url: Url,
+        target_dir: Path,
+        *,
+        media_types: list[MediaType] | None = None,
+        slice: Slice | None = None,
     ) -> dict[MediaType, Path]:
         path = self._parse_file_url(url)
         if not path:
             raise InvalidInput(f"Not a local file URL: {url}")
+        if slice:
+            raise NotImplementedError("Slicing currently not supported for local files")
 
         _name, _item_type, format, file_ext = parse_item_filename(path)
         os.makedirs(target_dir, exist_ok=True)

kash/model/actions_model.py

@@ -102,9 +102,9 @@ class ActionResult:
     shell_result: ShellResult | None = None
     """Customize control of how the action's result is displayed in the shell."""
 
-    def get_by_format(self, format: Format) -> Item:
+    def get_by_format(self, *formats: Format) -> Item:
         """Convenience method to get an item for actions that return multiple formats."""
-        return next(item for item in self.items if item.format == format)
+        return next(item for item in self.items if item.format in formats)
 
     def has_hints(self) -> bool:
         return bool(

kash/model/items_model.py

@@ -915,10 +915,10 @@ class Item:
                 key_filter={
                     "store_path": 0,
                     "type": 64,
-                    "title": 64,
+                    "format": 64,
+                    "title": 40,
                     "url": 64,
                     "external_path": 64,
-                    "context": 64,
                 },
             )
             + f"[{len(self.body) if self.body else 0} body chars]"
@@ -932,13 +932,12 @@ class Item:
                     "store_path": 0,
                     "external_path": 64,
                     "type": 64,
+                    "format": 64,
                     "state": 64,
-                    "title": 64,
+                    "title": 40,
                     "url": 64,
-                    "format": 64,
                     "created_at": 64,
                     "body": 64,
-                    "context": 64,
                 },
             )
             + f"[{len(self.body) if self.body else 0} body chars]"

kash/model/media_model.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from datetime import date
 from enum import Enum
@@ -7,6 +9,7 @@ from prettyfmt import abbrev_obj
 from pydantic.dataclasses import dataclass
 
 from kash.utils.common.url import Url
+from kash.utils.common.url_slice import Slice
 from kash.utils.file_utils.file_formats_model import MediaType
 
 
@@ -109,7 +112,12 @@ class MediaService(ABC):
 
     @abstractmethod
     def download_media(
-        self, url: Url, target_dir: Path, media_types: list[MediaType] | None = None
+        self,
+        url: Url,
+        target_dir: Path,
+        *,
+        media_types: list[MediaType] | None = None,
+        slice: Slice | None = None,
     ) -> dict[MediaType, Path]:
         """
         Download media from URL and extract to audio or video formats.

kash/model/params_model.py

@@ -206,10 +206,10 @@ A list of parameter declarations, possibly with default values.
 
 # These are the default models for typical use cases.
 # The user may override them with parameters.
-DEFAULT_CAREFUL_LLM = LLM.o1_preview
+DEFAULT_CAREFUL_LLM = LLM.o3
 DEFAULT_STRUCTURED_LLM = LLM.gpt_4o
-DEFAULT_STANDARD_LLM = LLM.claude_3_7_sonnet
-DEFAULT_FAST_LLM = LLM.claude_3_5_haiku
+DEFAULT_STANDARD_LLM = LLM.claude_4_sonnet
+DEFAULT_FAST_LLM = LLM.o1_mini
 
 
 # Parameters set globally such as in the workspace.
@@ -262,6 +262,12 @@ COMMON_ACTION_PARAMS: dict[str, Param] = {
         valid_str_values=list(LLM),
         is_open_ended=True,
     ),
+    "model_list": Param(
+        "model_list",
+        "A list of LLMs to use, as names separated by commas.",
+        type=str,
+        default_value=None,
+    ),
     "language": Param(
         "language",
         "The language of the input audio or text.",

kash/utils/common/function_inspect.py

@@ -4,7 +4,14 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum
 from inspect import Parameter
-from typing import Any, Union, cast, get_args, get_origin  # pyright: ignore[reportDeprecated]
+from typing import (
+    Any,
+    Literal,
+    Union,  # pyright: ignore[reportDeprecated]
+    cast,
+    get_args,
+    get_origin,
+)
 
 NO_DEFAULT = Parameter.empty  # Alias for clarity
 
@@ -90,6 +97,23 @@ def _resolve_type_details(annotation: Any) -> tuple[type | None, type | None, bo
             return (type(None), None, True)
         # If multiple non_none_args (e.g., int | str), current_annotation remains the Union for now.
 
+    # Handle Literal types
+    if origin is Literal:
+        if args:
+            # Determine the common type of all literal values
+            literal_types = {type(arg) for arg in args}
+            if len(literal_types) == 1:
+                # All literals are the same type
+                final_effective_type = literal_types.pop()
+            else:
+                # Mixed types, fall back to the most common base type or str if all are basic types
+                if all(isinstance(arg, (str, int, float, bool)) for arg in args):
+                    # For mixed basic types, use str as the effective type
+                    final_effective_type = str
+                else:
+                    final_effective_type = None
+            return final_effective_type, None, is_optional_flag
+
     #  Determine effective_type and inner_type from (potentially unwrapped) current_annotation
     final_effective_type: type | None = None
     final_inner_type: type | None = None
@@ -426,3 +450,75 @@ def test_inspect_function_parameters_updated():
             is_explicitly_optional=True,
         )
     ]
+
+
+def test_literal_types():
+    """Test Literal type support in function parameter inspection."""
+
+    # Test string literals
+    def func_string_literal(converter: Literal["markitdown", "marker"] = "markitdown"):
+        return converter
+
+    params = inspect_function_params(func_string_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "converter"
+    assert param.effective_type is str
+    assert param.default == "markitdown"
+    assert param.is_explicitly_optional is False
+
+    # Test integer literals
+    def func_int_literal(count: Literal[1, 2, 3] = 1):
+        return count
+
+    params = inspect_function_params(func_int_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "count"
+    assert param.effective_type is int
+    assert param.default == 1
+
+    # Test mixed type literals (should default to str)
+    def func_mixed_literal(value: Literal["auto", 42]):
+        return value
+
+    params = inspect_function_params(func_mixed_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "value"
+    assert param.effective_type is str
+    assert param.default == NO_DEFAULT
+
+    # Test Literal directly (without TypeAlias to avoid scope issues)
+    def func_direct_literal(converter: Literal["markitdown", "marker"] = "markitdown"):
+        return converter
+
+    params = inspect_function_params(func_direct_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "converter"
+    assert param.effective_type is str
+    assert param.default == "markitdown"
+
+    # Test optional literal
+    def func_optional_literal(mode: Literal["fast", "slow"] | None = None):
+        return mode
+
+    params = inspect_function_params(func_optional_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "mode"
+    assert param.effective_type is str
+    assert param.is_explicitly_optional is True
+    assert param.default is None
+
+    # Test boolean literals
+    def func_bool_literal(flag: Literal[True, False] = True):
+        return flag
+
+    params = inspect_function_params(func_bool_literal)
+    assert len(params) == 1
+    param = params[0]
+    assert param.name == "flag"
+    assert param.effective_type is bool
+    assert param.default is True

kash/utils/common/testing.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from functools import wraps
+from typing import Literal, TypeAlias
+
+TestMarker: TypeAlias = Literal["online", "integration"]
+"""
+Valid markers for tests. Currently just marking online tests (e.g. LLM APIs that
+that require keys) and more complex integration tests.
+"""
+
+
+def enable_if(marker: TestMarker) -> Callable:
+    """
+    Mark a test as having external dependencies.
+
+    Test runs only if the corresponding environment variable is set, e.g.
+    for the marker "online", checks for ENABLE_TESTS_ONLINE=1.
+
+    Automatically sets pytest markers when pytest is available, but safe to use in
+    runtime code as well.
+
+    Example usage:
+
+    ```
+    def test_foo():
+        ...
+
+    @enable_if("online")  # Only runs if ENABLE_TESTS_ONLINE=1
+    def test_bar():
+        ...
+    ```
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            env_var = f"ENABLE_TESTS_{marker.upper()}"
+            if not os.getenv(env_var):
+                print(f"Skipping test function: {func.__name__} (set {env_var}=1 to enable)")
+                return
+            return func(*args, **kwargs)
+
+        # Set pytest markers automatically if pytest is available
+        try:
+            import pytest
+
+            wrapper = pytest.mark.integration(wrapper)
+            wrapper = getattr(pytest.mark, marker)(wrapper)
+        except ImportError:
+            # Pytest not available, which is fine for non-test runs
+            pass
+
+        return wrapper
+
+    return decorator