kash-shell 0.3.8__py3-none-any.whl → 0.3.10__py3-none-any.whl

kash/media_base/media_cache.py

@@ -1,7 +1,7 @@
 import os
 from pathlib import Path
 
-from prettyfmt import fmt_lines
+from prettyfmt import fmt_lines, fmt_path
 from strif import atomic_output_file
 
 from kash.config.logger import get_logger
@@ -11,7 +11,7 @@ from kash.media_base.media_services import (
     download_media_by_service,
     get_media_services,
 )
-from kash.media_base.speech_transcription import deepgram_transcribe_audio
+from kash.media_base.transcription_deepgram import deepgram_transcribe_audio
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, as_file_url, is_url
 from kash.utils.errors import FileNotFound, InvalidInput, UnexpectedError
@@ -48,12 +48,12 @@ class MediaCache(DirStore):
         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_loc(transcript_path))
+        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)
         if transcript_file:
-            log.message("Video transcript already in cache: %s: %s", url, fmt_loc(transcript_file))
+            log.message("Video transcript already in cache: %s: %s", url, fmt_path(transcript_file))
             with open(transcript_file) as f:
                 return f.read()
         return None
@@ -67,8 +67,8 @@ class MediaCache(DirStore):
             downsampled_audio_file = self.path_for(url, suffix=SUFFIX_16KMP3)
             log.message(
                 "Downsampling audio: %s -> %s",
-                fmt_loc(full_audio_file),
-                fmt_loc(downsampled_audio_file),
+                fmt_path(full_audio_file),
+                fmt_path(downsampled_audio_file),
             )
             downsample_to_16khz(full_audio_file, downsampled_audio_file)
         return downsampled_audio_file
@@ -81,35 +81,35 @@ class MediaCache(DirStore):
         log.message(
             "Transcribing audio: %s: %s",
             url,
-            fmt_loc(downsampled_audio_file),
+            fmt_path(downsampled_audio_file),
         )
         transcript = transcribe_audio(downsampled_audio_file, language=language)
         self._write_transcript(url, transcript)
         return transcript
 
     def cache(
-        self, url: Url, no_cache=False, media_types: list[MediaType] | None = None
+        self, url: 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 `no_cache` is True.
+        unless `refetch` is True.
         """
         cached_paths: dict[MediaType, Path] = {}
 
         if not media_types:
             media_types = [MediaType.audio, MediaType.video]
 
-        if not no_cache:
+        if not refetch:
             if MediaType.audio in media_types:
                 audio_file = self.find(url, suffix=SUFFIX_MP3)
                 if audio_file:
-                    log.message("Audio already in cache: %s: %s", url, fmt_loc(audio_file))
+                    log.message("Audio already in cache: %s: %s", url, fmt_path(audio_file))
                     cached_paths[MediaType.audio] = audio_file
             if MediaType.video in media_types:
                 video_file = self.find(url, suffix=SUFFIX_MP4)
                 if video_file:
-                    log.message("Video already in cache: %s: %s", url, fmt_loc(video_file))
+                    log.message("Video already in cache: %s: %s", url, fmt_path(video_file))
                     cached_paths[MediaType.video] = video_file
             if set(media_types).issubset(cached_paths.keys()):
                 return cached_paths
@@ -133,7 +133,7 @@ class MediaCache(DirStore):
 
         log.message(
             "Downloaded media and saved to cache:\n%s",
-            fmt_lines([f"{t.name}: {fmt_loc(p)}" for (t, p) in cached_paths.items()]),
+            fmt_lines([f"{t.name}: {fmt_path(p)}" for (t, p) in cached_paths.items()]),
         )
 
         self._downsample_audio(url)
@@ -141,11 +141,11 @@ class MediaCache(DirStore):
         return cached_paths
 
     def transcribe(
-        self, url_or_path: Url | Path, no_cache=False, language: str | None = None
+        self, url_or_path: Url | Path, refetch=False, language: str | None = None
     ) -> str:
         """
         Transcribe the audio file, caching audio, downsampled audio, and the transcription.
-        Return the cached transcript if available, unless `no_cache` is True.
+        Return the cached transcript if available, unless `refetch` is True.
         """
         if not isinstance(url_or_path, Path) and is_url(url_or_path):
             # If it is a URL, cache it locally.
@@ -156,12 +156,12 @@ class MediaCache(DirStore):
                 raise InvalidInput(
                     "Unrecognized media URL (is this media service configured?): %s" % url_or_path
                 )
-            if not no_cache:
+            if not refetch:
                 transcript = self._read_transcript(url)
                 if transcript:
                     return transcript
             # Cache all formats since we usually will want them.
-            self.cache(url, no_cache)
+            self.cache(url, 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.
@@ -169,7 +169,7 @@ class MediaCache(DirStore):
                 raise FileNotFound(f"File not found: {fmt_loc(url_or_path)}")
             url = as_file_url(url_or_path)
         else:
-            raise InvalidInput(f"Not a media URL or path: {url_or_path}")
+            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)

kash/media_base/media_services.py

@@ -2,10 +2,10 @@ import logging
 from pathlib import Path
 
 from funlog import log_calls
+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.atomic_var import AtomicVar
 from kash.utils.common.url import Url
 from kash.utils.errors import InvalidInput
 from kash.utils.file_utils.file_formats_model import MediaType

kash/media_base/media_tools.py

@@ -28,20 +28,20 @@ def reset_media_cache_dir(path: Path):
 
 
 def cache_and_transcribe(
-    url_or_path: Url | Path, no_cache=False, language: str | None = None
+    url_or_path: Url | Path, refetch=False, language: str | None = None
 ) -> str:
     """
-    Download and transcribe audio or video, saving in cache. If no_cache is
+    Download and transcribe audio or video, saving in cache. If `refetch` is
     True, force fresh download.
     """
-    return _media_cache.transcribe(url_or_path, no_cache=no_cache, language=language)
+    return _media_cache.transcribe(url_or_path, refetch=refetch, language=language)
 
 
 def cache_media(
-    url: Url, no_cache=False, media_types: list[MediaType] | None = None
+    url: Url, refetch=False, media_types: list[MediaType] | None = None
 ) -> dict[MediaType, Path]:
     """
-    Download audio and video (if available), saving in cache. If no_cache is
+    Download audio and video (if available), saving in cache. If refetch is
     True, force fresh download.
     """
-    return _media_cache.cache(url, no_cache, media_types)
+    return _media_cache.cache(url, refetch, media_types)

kash/media_base/services/local_file_media.py

@@ -4,13 +4,13 @@ import subprocess  # Add this import
 from pathlib import Path
 from urllib.parse import urlparse
 
+from clideps.pkgs.pkg_check import pkg_check
 from strif import copyfile_atomic
 from typing_extensions import override
 
 from kash.config.logger import get_log_file_stream, get_logger
 from kash.file_storage.store_filenames import parse_item_filename
 from kash.model.media_model import MediaMetadata, MediaService, MediaUrlType
-from kash.shell.clideps.pkg_deps import Pkg, pkg_check
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url
 from kash.utils.errors import FileNotFound, InvalidInput
@@ -20,7 +20,7 @@ log = get_logger(__name__)
 
 
 def _run_ffmpeg(cmdline: list[str]) -> None:
-    pkg_check().require(Pkg.ffmpeg)
+    pkg_check().require("ffmpeg")
     log.message("Running: %s", " ".join([shlex.quote(arg) for arg in cmdline]))
     subprocess.run(
         cmdline,

kash/media_base/{speech_transcription.py → transcription_deepgram.py}

@@ -1,60 +1,23 @@
 from os.path import getsize
 from pathlib import Path
-from typing import NamedTuple
 
+from clideps.env_vars.dotenv_utils import load_dotenv_paths
+from deepgram import ListenRESTClient, PrerecordedResponse
 from httpx import Timeout
-from openai import OpenAI
 
 from kash.config.logger import CustomLogger, get_logger
-from kash.media_base.timestamp_citations import html_speaker_id_span, html_timestamp_span
-from kash.shell.clideps.dotenv_utils import load_dotenv_paths
-from kash.utils.errors import ContentError
+from kash.config.settings import global_settings
+from kash.media_base.transcription_format import SpeakerSegment, format_speaker_segments
+from kash.utils.errors import ApiError, ContentError
 
 log: CustomLogger = get_logger(__name__)
 
 
-def openai_whisper_transcribe_audio_small(audio_file_path: str) -> str:
+def deepgram_transcribe_raw(
+    audio_file_path: Path, language: str | None = None
+) -> PrerecordedResponse:
     """
-    Transcribe an audio file. Whisper is very good quality but (as of 2024-05)
-    OpenAI's version does not support diarization and must be under 25MB.
-
-    https://help.openai.com/en/articles/7031512-whisper-api-faq
-    """
-    WHISPER_MAX_SIZE = 25 * 1024 * 1024
-
-    size = getsize(audio_file_path)
-    if size > WHISPER_MAX_SIZE:
-        raise ValueError("Audio file too large for Whisper (%s > %s)" % (size, WHISPER_MAX_SIZE))
-    log.info(
-        "Transcribing via Whisper: %s (size %s)",
-        audio_file_path,
-        size,
-    )
-
-    client = OpenAI()
-    with open(audio_file_path, "rb") as audio_file:
-        transcription = client.audio.transcriptions.create(
-            model="whisper-1",
-            file=audio_file,
-            # For when we want timestamps:
-            # response_format="verbose_json",
-            # timestamp_granularities=["word"]
-        )
-        text = transcription.text
-    return text
-
-
-class SpeakerSegment(NamedTuple):
-    words: list[tuple[float, str]]
-    start: float
-    end: float
-    speaker: int
-    average_confidence: float
-
-
-def deepgram_transcribe_audio(audio_file_path: Path, language: str | None = None) -> str:
-    """
-    Transcribe an audio file using Deepgram.
+    Transcribe an audio file using Deepgram and return the raw response.
     """
     from deepgram import ClientOptionsFromEnv, DeepgramClient, FileSource, PrerecordedOptions
 
@@ -63,7 +26,7 @@ def deepgram_transcribe_audio(audio_file_path: Path, language: str | None = None
         "Transcribing via Deepgram (language %r): %s (size %s)", language, audio_file_path, size
     )
 
-    load_dotenv_paths()
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
     deepgram = DeepgramClient("", ClientOptionsFromEnv())
 
     with open(audio_file_path, "rb") as audio_file:
@@ -74,7 +37,17 @@ def deepgram_transcribe_audio(audio_file_path: Path, language: str | None = None
     }
 
     options = PrerecordedOptions(model="nova-2", smart_format=True, diarize=True, language=language)
-    response = deepgram.listen.rest.v("1").transcribe_file(payload, options, timeout=Timeout(500))  # pyright: ignore
+    client: ListenRESTClient = deepgram.listen.rest.v("1")  # pyright: ignore
+
+    response = client.transcribe_file(payload, options, timeout=Timeout(500))
+    if not isinstance(response, PrerecordedResponse):
+        raise ApiError("Deepgram returned an unexpected response type")
+
+    return response
+
+
+def deepgram_transcribe_audio(audio_file_path: Path, language: str | None = None) -> str:
+    response = deepgram_transcribe_raw(audio_file_path, language)
 
     log.save_object("Deepgram response", None, response)
 
@@ -86,13 +59,15 @@ def deepgram_transcribe_audio(audio_file_path: Path, language: str | None = None
             f"No speaker segments found in Deepgram response (are voices silent or missing?): {audio_file_path}"
         )
 
-    formatted_segments = format_speaker_segments(diarized_segments)
+    formatted_segments = format_speaker_segments(diarized_segments)  # noqa: F821
 
     return formatted_segments
 
 
 def _deepgram_diarized_segments(data, confidence_threshold=0.3) -> list[SpeakerSegment]:
-    """Process Deepgram diarized results into text segments per speaker."""
+    """
+    Process Deepgram diarized results into text segments per speaker.
+    """
 
     speaker_segments: list[SpeakerSegment] = []
     current_speaker = 0
@@ -163,62 +138,3 @@ def _deepgram_diarized_segments(data, confidence_threshold=0.3) -> list[SpeakerS
         )
 
     return speaker_segments
-
-
-def _is_new_sentence(word: str, next_word: str | None) -> bool:
-    return (
-        (word.endswith(".") or word.endswith("?") or word.endswith("!"))
-        and next_word is not None
-        and next_word[0].isupper()
-    )
-
-
-def _format_words(words: list[tuple[float, str]], include_sentence_timestamps=True) -> str:
-    """Format words with timestamps added in spans."""
-
-    if not words:
-        return ""
-
-    sentences = []
-    current_sentence = []
-    for i, (timestamp, word) in enumerate(words):
-        current_sentence.append(word)
-        next_word = words[i + 1][1] if i + 1 < len(words) else None
-        if _is_new_sentence(word, next_word):
-            sentences.append((timestamp, current_sentence))
-            current_sentence = []
-
-    if current_sentence:
-        sentences.append((words[-1][0], current_sentence))
-
-    formatted_text = []
-    for timestamp, sentence in sentences:
-        formatted_sentence = " ".join(sentence)
-        if include_sentence_timestamps:
-            formatted_text.append(html_timestamp_span(formatted_sentence, timestamp))
-        else:
-            formatted_text.append(formatted_sentence)
-
-    return "\n".join(formatted_text)
-
-
-def format_speaker_segments(speaker_segments: list[SpeakerSegment]) -> str:
-    """
-    Format speaker segments in a simple HTML format with <span> tags including speaker
-    ids and timestamps.
-    """
-
-    # Use \n\n for readability between segments so each speaker is its own
-    # paragraph.
-    SEGMENT_SEP = "\n\n"
-
-    speakers = set(segment.speaker for segment in speaker_segments)
-    if len(speakers) > 1:
-        lines = []
-        for segment in speaker_segments:
-            lines.append(
-                f"{html_speaker_id_span(f'SPEAKER {segment.speaker}:', str(segment.speaker))}\n{_format_words(segment.words)}"
-            )
-        return SEGMENT_SEP.join(lines)
-    else:
-        return SEGMENT_SEP.join(_format_words(segment.words) for segment in speaker_segments)

kash/media_base/transcription_format.py

@@ -0,0 +1,73 @@
+from typing import NamedTuple
+
+from kash.config.logger import CustomLogger, get_logger
+from kash.media_base.timestamp_citations import html_speaker_id_span, html_timestamp_span
+
+log: CustomLogger = get_logger(__name__)
+
+
+def _is_new_sentence(word: str, next_word: str | None) -> bool:
+    return (
+        (word.endswith(".") or word.endswith("?") or word.endswith("!"))
+        and next_word is not None
+        and next_word[0].isupper()
+    )
+
+
+def _format_words(words: list[tuple[float, str]], include_sentence_timestamps=True) -> str:
+    """Format words with timestamps added in spans."""
+
+    if not words:
+        return ""
+
+    sentences = []
+    current_sentence = []
+    for i, (timestamp, word) in enumerate(words):
+        current_sentence.append(word)
+        next_word = words[i + 1][1] if i + 1 < len(words) else None
+        if _is_new_sentence(word, next_word):
+            sentences.append((timestamp, current_sentence))
+            current_sentence = []
+
+    if current_sentence:
+        sentences.append((words[-1][0], current_sentence))
+
+    formatted_text = []
+    for timestamp, sentence in sentences:
+        formatted_sentence = " ".join(sentence)
+        if include_sentence_timestamps:
+            formatted_text.append(html_timestamp_span(formatted_sentence, timestamp))
+        else:
+            formatted_text.append(formatted_sentence)
+
+    return "\n".join(formatted_text)
+
+
+class SpeakerSegment(NamedTuple):
+    words: list[tuple[float, str]]
+    start: float
+    end: float
+    speaker: int
+    average_confidence: float
+
+
+def format_speaker_segments(speaker_segments: list[SpeakerSegment]) -> str:
+    """
+    Format speaker segments in a simple HTML format with <span> tags including speaker
+    ids and timestamps.
+    """
+
+    # Use \n\n for readability between segments so each speaker is its own
+    # paragraph.
+    SEGMENT_SEP = "\n\n"
+
+    speakers = set(segment.speaker for segment in speaker_segments)
+    if len(speakers) > 1:
+        lines = []
+        for segment in speaker_segments:
+            lines.append(
+                f"{html_speaker_id_span(f'SPEAKER {segment.speaker}:', str(segment.speaker))}\n{_format_words(segment.words)}"
+            )
+        return SEGMENT_SEP.join(lines)
+    else:
+        return SEGMENT_SEP.join(_format_words(segment.words) for segment in speaker_segments)

kash/media_base/transcription_whisper.py

@@ -0,0 +1,38 @@
+from os.path import getsize
+
+from openai import OpenAI
+
+from kash.config.logger import CustomLogger, get_logger
+
+log: CustomLogger = get_logger(__name__)
+
+
+def openai_whisper_transcribe_audio_small(audio_file_path: str) -> str:
+    """
+    Transcribe an audio file. Whisper is very good quality but (as of 2024-05)
+    OpenAI's version does not support diarization and must be under 25MB.
+
+    https://help.openai.com/en/articles/7031512-whisper-api-faq
+    """
+    WHISPER_MAX_SIZE = 25 * 1024 * 1024
+
+    size = getsize(audio_file_path)
+    if size > WHISPER_MAX_SIZE:
+        raise ValueError("Audio file too large for Whisper (%s > %s)" % (size, WHISPER_MAX_SIZE))
+    log.info(
+        "Transcribing via Whisper: %s (size %s)",
+        audio_file_path,
+        size,
+    )
+
+    client = OpenAI()
+    with open(audio_file_path, "rb") as audio_file:
+        transcription = client.audio.transcriptions.create(
+            model="whisper-1",
+            file=audio_file,
+            # For when we want timestamps:
+            # response_format="verbose_json",
+            # timestamp_granularities=["word"]
+        )
+        text = transcription.text
+    return text

kash/model/__init__.py

@@ -1,11 +1,7 @@
 """
 The core classes for modeling kash's framework.
-
-We include essential logic here but try to keep logic and dependencies minimal.
 """
 
-# flake8: noqa: F401
-
 from kash.exec_model.args_model import (
     ANY_ARGS,
     NO_ARGS,
@@ -31,7 +27,12 @@ from kash.model.actions_model import (
     PerItemAction,
     TitleTemplate,
 )
-from kash.model.compound_actions_model import ComboAction, SequenceAction, look_up_actions
+from kash.model.compound_actions_model import (
+    ComboAction,
+    SequenceAction,
+    look_up_actions,
+)
+from kash.model.concept_model import Concept, canonicalize_concept, normalize_concepts
 from kash.model.graph_model import GraphData, Link, Node
 from kash.model.items_model import (
     SLUG_MAX_LEN,
@@ -69,3 +70,70 @@ from kash.model.paths_model import StorePath
 from kash.model.preconditions_model import Precondition
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.file_utils.file_formats_model import FileExt, Format, MediaType
+
+__all__ = [
+    "ANY_ARGS",
+    "NO_ARGS",
+    "ONE_ARG",
+    "ONE_OR_MORE_ARGS",
+    "ONE_OR_NO_ARGS",
+    "TWO_ARGS",
+    "TWO_OR_MORE_ARGS",
+    "ArgCount",
+    "CommandArg",
+    "Command",
+    "CommentedCommand",
+    "BareComment",
+    "Script",
+    "ShellResult",
+    "Action",
+    "ActionInput",
+    "ActionResult",
+    "ExecContext",
+    "LLMOptions",
+    "PathOp",
+    "PathOpType",
+    "PerItemAction",
+    "TitleTemplate",
+    "ComboAction",
+    "SequenceAction",
+    "look_up_actions",
+    "Concept",
+    "canonicalize_concept",
+    "normalize_concepts",
+    "GraphData",
+    "Link",
+    "Node",
+    "SLUG_MAX_LEN",
+    "UNTITLED",
+    "IdType",
+    "Item",
+    "ItemId",
+    "ItemRelations",
+    "ItemType",
+    "State",
+    "SERVICE_APPLE_PODCASTS",
+    "SERVICE_VIMEO",
+    "SERVICE_YOUTUBE",
+    "HeatmapValue",
+    "MediaMetadata",
+    "MediaService",
+    "MediaUrlType",
+    "ALL_COMMON_PARAMS",
+    "COMMON_ACTION_PARAMS",
+    "GLOBAL_PARAMS",
+    "RUNTIME_ACTION_PARAMS",
+    "USER_SETTABLE_PARAMS",
+    "Param",
+    "ParamDeclarations",
+    "RawParamValues",
+    "TypedParamValues",
+    "common_param",
+    "common_params",
+    "StorePath",
+    "Precondition",
+    "fmt_loc",
+    "FileExt",
+    "Format",
+    "MediaType",
+]

kash/model/actions_model.py

@@ -9,12 +9,12 @@ from textwrap import dedent
 from typing import Any, TypeVar, cast
 
 from chopdiff.docs import DiffFilter
-from chopdiff.docs.token_diffs import DIFF_FILTER_NONE
 from chopdiff.transforms import WINDOW_NONE, WindowSettings
 from flowmark import fill_text
 from prettyfmt import abbrev_obj, fmt_lines
 from pydantic.dataclasses import dataclass, rebuild_dataclass
 from pydantic.json_schema import JsonSchemaValue
+from strif import StringTemplate
 from typing_extensions import override
 
 from kash.config.logger import get_logger
@@ -27,13 +27,15 @@ from kash.model.items_model import UNTITLED, Item, ItemType, State
 from kash.model.operations_model import Operation, Source
 from kash.model.params_model import (
     ALL_COMMON_PARAMS,
+    COMMON_SHELL_PARAMS,
+    RUNTIME_ACTION_PARAMS,
+    Param,
     ParamDeclarations,
     TypedParamValues,
 )
 from kash.model.paths_model import StorePath
 from kash.model.preconditions_model import Precondition
 from kash.utils.common.parse_key_vals import format_key_value
-from kash.utils.common.string_template import StringTemplate
 from kash.utils.common.type_utils import not_none
 from kash.utils.errors import InvalidDefinition, InvalidInput
 from kash.workspaces.workspaces import get_ws
@@ -65,7 +67,8 @@ class ActionInput:
 @dataclass(frozen=True)
 class ExecContext:
     """
-    An action and its context for execution.
+    An action and its context for execution. This is a good place for settings
+    that apply to any action and are bothersome to pass as parameters.
     """
 
     action: Action
@@ -77,13 +80,33 @@ class ExecContext:
     rerun: bool = False
     """If True, always run actions, even cacheable ones that have results."""
 
+    refetch: bool = False
+    """If True, will refetch items even if they are already in the content caches."""
+
     override_state: State | None = None
     """If specified, override the state of result items. Useful to mark items as transient."""
 
+    tmp_output: bool = False
+    """If True, will save output items to a temporary file."""
+
+    no_format: bool = False
+    """If True, will not normalize the output item's body text formatting (for Markdown)."""
+
     @property
     def workspace(self) -> FileStore:
         return get_ws(self.workspace_dir)
 
+    @property
+    def runtime_options(self) -> dict[str, str]:
+        """Return non-default runtime options."""
+        opts: dict[str, str] = {}
+        # Only these two settings directly affect the output:
+        if self.no_format:
+            opts["no_format"] = "true"
+        if self.override_state:
+            opts["override_state"] = self.override_state.name
+        return opts
+
     def __repr__(self):
         return abbrev_obj(self, field_max_len=80)
 
@@ -175,7 +198,7 @@ class LLMOptions:
     system_message: Message = Message("")
     body_template: MessageTemplate = MessageTemplate("{body}")
     windowing: WindowSettings = WINDOW_NONE
-    diff_filter: DiffFilter = DIFF_FILTER_NONE
+    diff_filter: DiffFilter | None = None
 
     def updated_with(self, param_name: str, value: Any) -> LLMOptions:
         """Update option from an action parameter."""
@@ -409,6 +432,17 @@ class Action(ABC):
         # Update corresponding LLM option if appropriate.
         self.llm_options = self.llm_options.updated_with(param_name, value)
 
+    @property
+    def shell_params(self) -> list[Param]:
+        """
+        List of parameters that are relevant to shell usage.
+        """
+        return (
+            list(self.params)
+            + list(RUNTIME_ACTION_PARAMS.values())
+            + list(COMMON_SHELL_PARAMS.values())
+        )
+
     def param_value_summary(self) -> dict[str, str]:
         """
         Readable, serializable summary of the action's non-default parameters, to include in