kash-shell 0.3.12__py3-none-any.whl → 0.3.13__py3-none-any.whl

kash/file_storage/file_store.py

@@ -182,12 +182,37 @@ class FileStore(Workspace):
         except (FileNotFoundError, InvalidFilename):
             pass
 
+    def resolve_path(self, path: Path | StorePath) -> StorePath | None:
+        """
+        Return a StorePath if the given path is within the store, otherwise None.
+        If it is already a StorePath, return it unchanged.
+        """
+        if isinstance(path, StorePath):
+            return path
+        resolved = path.resolve()
+        if resolved.is_relative_to(self.base_dir):
+            return StorePath(resolved.relative_to(self.base_dir))
+        else:
+            return None
+
+    def exists(self, store_path: StorePath) -> bool:
+        """
+        Check given store path refers to an existing file.
+        """
+        return (self.base_dir / store_path).exists()
+
     @synchronized
-    def _new_filename_for(self, item: Item) -> tuple[str, str | None]:
+    def _pick_filename_for(self, item: Item, *, overwrite: bool = False) -> tuple[str, str | None]:
         """
-        Get a suitable filename for this item that is close to the slugified title yet also unique.
-        Also return the old filename if it's different.
+        Get a suitable filename for this item.
+        If `overwrite` is true, use the the slugified title.
+        If it is false, use the slugified title with a suffix to make it unique
+        and in this case returns the old filename for this item, if it is different.
         """
+        if overwrite:
+            log.info("Picked default filename: %s for item: %s", item.default_filename(), item)
+            return item.default_filename(), None
+
         slug = item.slug_name()
         full_suffix = item.get_full_suffix()
         # Get a unique name per item type.
@@ -198,29 +223,15 @@ class FileStore(Workspace):
 
         old_filename = join_suffix(old_slugs[0], full_suffix) if old_slugs else None
 
+        log.info("Picked new unique filename: %s for item: %s", new_unique_filename, item)
         return new_unique_filename, old_filename
 
-    def _default_path_for(self, item: Item) -> StorePath:
-        folder_path = folder_for_type(item.type)
-        slug = item.slug_name()
-        suffix = item.get_full_suffix()
-        return StorePath(folder_path / join_suffix(slug, suffix))
-
-    def exists(self, store_path: StorePath) -> bool:
-        return (self.base_dir / store_path).exists()
-
-    def resolve_path(self, path: Path | StorePath) -> StorePath | None:
+    def default_path_for(self, item: Item) -> StorePath:
         """
-        Return a StorePath if the given path is within the store, otherwise None.
-        If it is already a StorePath, return it unchanged.
+        Get the default store path for an item based on slugifying its title or other metadata.
         """
-        if isinstance(path, StorePath):
-            return path
-        resolved = path.resolve()
-        if resolved.is_relative_to(self.base_dir):
-            return StorePath(resolved.relative_to(self.base_dir))
-        else:
-            return None
+        folder_path = folder_for_type(item.type)
+        return StorePath(folder_path / item.default_filename())
 
     @synchronized
     def find_by_id(self, item: Item) -> StorePath | None:
@@ -235,7 +246,7 @@ class FileStore(Workspace):
             store_path = self.id_map.get(item_id)
             if not store_path:
                 # Just in case the id_map is not complete, check the default path too.
-                default_path = self._default_path_for(item)
+                default_path = self.default_path_for(item)
                 if self.exists(default_path):
                     old_item = self.load(default_path)
                     if old_item.item_id() == item_id:
@@ -256,7 +267,7 @@ class FileStore(Workspace):
 
     @synchronized
     def store_path_for(
-        self, item: Item, as_tmp: bool = False
+        self, item: Item, *, as_tmp: bool = False, overwrite: bool = False
     ) -> tuple[StorePath, bool, StorePath | None]:
         """
         Return the store path for an item. If the item already has a `store_path`, we use that.
@@ -265,6 +276,10 @@ class FileStore(Workspace):
         Returns `store_path, found, old_store_path` where `found` indicates whether the path was
         already found (in the item or in the store by checking for identity) and `old_store_path`
         is the previous similarly named item with a different identity (or None there is none).
+
+        If `as_tmp` is true, will return a path from the temporary directory in the store.
+        Normally an item is always saved to a unique store path but if `overwrite` is true,
+        will always save to the same path
         """
         item_id = item.item_id()
         old_filename = None
@@ -281,9 +296,9 @@ class FileStore(Workspace):
             )
             return store_path, True, None
         else:
-            # We need to generate a new filename.
+            # We need to pick the path and filename.
             folder_path = folder_for_type(item.type)
-            filename, old_filename = self._new_filename_for(item)
+            filename, old_filename = self._pick_filename_for(item, overwrite=overwrite)
             store_path = folder_path / filename
 
             old_store_path = None
@@ -312,7 +327,13 @@ class FileStore(Workspace):
 
     @log_calls()
     def save(
-        self, item: Item, *, overwrite: bool = True, as_tmp: bool = False, no_format: bool = False
+        self,
+        item: Item,
+        *,
+        overwrite: bool = False,
+        skip_dup_names: bool = False,
+        as_tmp: bool = False,
+        no_format: bool = False,
     ) -> StorePath:
         """
         Save the item. Uses the `store_path` if it's already set or generates a new one.
@@ -321,9 +342,18 @@ class FileStore(Workspace):
         Unless `no_format` is true, also normalizes body text formatting (for Markdown)
         and updates the item's body to match.
 
+        If `overwrite` is true, will overwrite a file that has the same path.
+
         If `as_tmp` is true, will save the item to a temporary file.
-        If `overwrite` is false, will skip saving if the item already exists.
+
+        If `skip_dup_names` is true, will skip saving if an item if an item with a
+        matching path (based on its title) already exists.
         """
+        if overwrite and skip_dup_names:
+            raise ValueError("Cannot both overwrite and skip duplicate names.")
+        if overwrite and as_tmp:
+            raise ValueError("Cannot both overwrite and save to a temporary file.")
+
         # If external file already exists within the workspace, the file is already saved (without metadata).
         external_path = item.external_path and Path(item.external_path).resolve()
         if external_path and self._is_in_store(external_path):
@@ -335,10 +365,15 @@ class FileStore(Workspace):
             return StorePath(rel_path)
         else:
             # Otherwise it's still in memory or in a file outside the workspace and we need to save it.
-            store_path, found, old_store_path = self.store_path_for(item, as_tmp=as_tmp)
+            store_path, found, old_store_path = self.store_path_for(
+                item, as_tmp=as_tmp, overwrite=overwrite
+            )
 
-            if not overwrite and found:
-                log.message("Skipping save of item already saved: %s", fmt_loc(store_path))
+            if skip_dup_names and found:
+                log.message(
+                    "Skipping save because an item of the same name already exists: %s",
+                    fmt_loc(store_path),
+                )
                 item.store_path = str(store_path)
                 return store_path
 
@@ -356,8 +391,14 @@ class FileStore(Workspace):
             # Now save the new item.
             try:
                 if item.external_path:
-                    copyfile_atomic(item.external_path, full_path)
+                    copyfile_atomic(item.external_path, full_path, make_parents=True)
                 else:
+                    if overwrite and full_path.exists():
+                        log.info(
+                            "Overwrite is enabled and a previous file exists so will archive it: %s",
+                            fmt_loc(store_path),
+                        )
+                        self.archive(store_path, quiet=True)
                     write_item(item, full_path, normalize=not no_format)
             except OSError as e:
                 log.error("Error saving item: %s", e)

kash/file_storage/item_file_format.py

@@ -7,10 +7,10 @@ from prettyfmt import custom_key_sort, fmt_size_human
 from kash.config.logger import get_logger
 from kash.model.items_model import ITEM_FIELDS, Item
 from kash.model.operations_model import OPERATION_FIELDS
-from kash.text_handling.doc_normalization import normalize_formatting
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.file_utils.file_formats_model import Format
 from kash.utils.file_utils.mtime_cache import MtimeCache
+from kash.utils.text_handling.doc_normalization import normalize_formatting
 
 log = get_logger(__name__)
 

kash/file_storage/store_filenames.py

@@ -1,9 +1,10 @@
 from functools import cache
 from pathlib import Path
 
+from prettyfmt import plural
+
 from kash.config.logger import get_logger
 from kash.model.items_model import ItemType
-from kash.utils.common.inflection import plural
 from kash.utils.file_utils.file_formats_model import FileExt, Format
 from kash.utils.file_utils.filename_parsing import split_filename
 

kash/help/help_embeddings.py

@@ -62,9 +62,9 @@ class HelpIndex:
             embeddings.to_npz(target_path)
 
         key = f"kash_help_embeddings_v1_{len(self.docs)}.npz"
-        path, _ = cache_file(
+        path = cache_file(
             Loadable(key, save=calculate_and_save_help_embeddings), global_cache=True
-        )
+        ).content.path
         log.info("Loaded help doc embeddings from: %s", path)
         return Embeddings.read_from_npz(path)
 

kash/llm_utils/clean_headings.py

@@ -1,6 +1,6 @@
 from kash.llm_utils import Message, MessageTemplate, llm_template_completion
 from kash.llm_utils.llms import LLM
-from kash.text_handling.markdown_utils import as_bullet_points
+from kash.utils.text_handling.markdown_utils import as_bullet_points
 
 # TODO: Enforce that the edits below doesn't contain anything extraneous.
 

kash/{text_handling → llm_utils}/custom_sliding_transforms.py

@@ -31,9 +31,6 @@ log = get_logger(__name__)
 # more customized logging and task stack.
 
 
-log = get_logger(__name__)
-
-
 def filtered_transform(
     doc: TextDoc,
     transform_func: TextDocTransform,

kash/llm_utils/llm_completion.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 import time
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
 from flowmark import Wrap, fill_text
 from funlog import format_duration, log_calls
 from prettyfmt import slugify_snake
 from pydantic import BaseModel
-from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.config.text_styles import EMOJI_TIMING

kash/local_server/__init__.py

@@ -2,4 +2,4 @@ from pathlib import Path
 
 from kash.exec.importing import import_and_register
 
-import_and_register(__package__, Path(__file__).parent, ["."])
+import_and_register(__package__, Path(__file__).parent, ["local_server_commands"])

kash/local_server/local_server_commands.py

@@ -1,7 +1,6 @@
 from kash.config.logger import get_logger
 from kash.config.settings import global_settings
 from kash.exec import kash_command
-from kash.local_server.local_url_formatters import enable_local_urls
 from kash.shell.utils.native_utils import tail_file
 from kash.utils.errors import InvalidState
 
@@ -17,6 +16,7 @@ def start_ui_server() -> None:
     tooltips.
     """
     from kash.local_server.local_server import start_ui_server
+    from kash.local_server.local_url_formatters import enable_local_urls
 
     start_ui_server()
     enable_local_urls(True)
@@ -28,6 +28,7 @@ def stop_ui_server() -> None:
     Stop the kash local server.
     """
     from kash.local_server.local_server import stop_ui_server
+    from kash.local_server.local_url_formatters import enable_local_urls
 
     stop_ui_server()
     enable_local_urls(False)

kash/mcp/__init__.py

@@ -2,4 +2,4 @@ from pathlib import Path
 
 from kash.exec.importing import import_and_register
 
-import_and_register(__package__, Path(__file__).parent, ["."])
+import_and_register(__package__, Path(__file__).parent, ["mcp_server_commands"])

kash/mcp/mcp_server_commands.py

@@ -6,8 +6,6 @@ from kash.config.settings import (
     global_settings,
 )
 from kash.exec import kash_command
-from kash.mcp import mcp_server_routes
-from kash.mcp.mcp_cli import MCP_CLI_LOG_PATH
 from kash.shell.output.shell_formatting import format_name_and_value
 from kash.shell.output.shell_output import cprint, print_h2
 from kash.shell.utils.native_utils import tail_file
@@ -21,6 +19,7 @@ def start_mcp_server() -> None:
     """
     Start the MCP server, using all currently known actions marked as MCP tools.
     """
+    from kash.mcp import mcp_server_routes
     from kash.mcp.mcp_server_sse import start_mcp_server_sse
 
     mcp_server_routes.publish_mcp_tools()
@@ -42,6 +41,7 @@ def restart_mcp_server() -> None:
     """
     Restart the MCP server, republishing all actions marked as MCP tools.
     """
+    from kash.mcp import mcp_server_routes
     from kash.mcp.mcp_server_sse import restart_mcp_server_sse
 
     mcp_server_routes.unpublish_mcp_tools(None)
@@ -57,6 +57,8 @@ def mcp_logs(follow: bool = False, all: bool = False) -> None:
     :param follow: Follow the file as it grows.
     :param all: Show all logs, not just the server logs, including Claude Desktop logs if found.
     """
+    from kash.mcp.mcp_cli import MCP_CLI_LOG_PATH
+
     settings = global_settings()
     if all:
         global_log_base = settings.system_logs_dir
@@ -96,6 +98,7 @@ def list_mcp_tools() -> None:
     """
     List published MCP tools.
     """
+    from kash.mcp import mcp_server_routes
 
     tools = mcp_server_routes.get_published_tools()
 
@@ -118,6 +121,8 @@ def publish_mcp_tool(*action_names: str) -> None:
     Publish one or more actions as local MCP tools. With no arguments, publish all
     actions marked as MCP tools.
     """
+    from kash.mcp import mcp_server_routes
+
     if not action_names:
         log.message("Publishing all actions marked as MCP tools.")
         mcp_server_routes.publish_mcp_tools()
@@ -131,6 +136,7 @@ def unpublish_mcp_tool(*action_names: str) -> None:
     Un-publish one or more actions as local MCP tools. With no arguments,
     un-publish all published actions.
     """
+    from kash.mcp import mcp_server_routes
 
     if not action_names:
         log.message("Un-publishing all actions marked as MCP tools.")

kash/media_base/media_cache.py

@@ -1,4 +1,5 @@
 import os
+from functools import cache
 from pathlib import Path
 
 from prettyfmt import fmt_lines, fmt_path
@@ -11,7 +12,6 @@ from kash.media_base.media_services import (
     download_media_by_service,
     get_media_services,
 )
-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
@@ -22,7 +22,14 @@ log = get_logger(__name__)
 
 # FIXME: Hard-coded dependency for now. Would be better to make it settable.
 # transcribe_audio = whisper_transcribe_audio_small
-transcribe_audio = deepgram_transcribe_audio
+
+
+@cache
+def get_transcriber():
+    from kash.media_base.transcription_deepgram import deepgram_transcribe_audio
+
+    transcribe_audio = deepgram_transcribe_audio
+    return transcribe_audio
 
 
 # For simplicity we assume all audio is converted to mp3.
@@ -83,7 +90,7 @@ class MediaCache(DirStore):
             url,
             fmt_path(downsampled_audio_file),
         )
-        transcript = transcribe_audio(downsampled_audio_file, language=language)
+        transcript = get_transcriber()(downsampled_audio_file, language=language)
         self._write_transcript(url, transcript)
         return transcript
 

kash/model/actions_model.py

@@ -90,6 +90,9 @@ class ActionResult:
     replaces_input: bool = False
     """If True, a hint to archive the input items."""
 
+    overwrite: bool = False
+    """If True, will not pick unique output paths to save to, overwriting existing files of the same name."""
+
     skip_duplicates: bool = False
     """If True, do not save duplicate items (based on identity)."""
 

kash/model/items_model.py

@@ -24,13 +24,14 @@ from kash.model.concept_model import canonicalize_concept
 from kash.model.media_model import MediaMetadata
 from kash.model.operations_model import OperationSummary, Source
 from kash.model.paths_model import StorePath, fmt_store_path
-from kash.text_handling.markdown_render import markdown_to_html
-from kash.text_handling.markdown_utils import first_heading
 from kash.utils.common.format_utils import fmt_loc, html_to_plaintext, plaintext_to_html
 from kash.utils.common.url import Locator, Url
 from kash.utils.errors import FileFormatError
 from kash.utils.file_formats.chat_format import ChatHistory
+from kash.utils.file_utils.file_formats import MimeType
 from kash.utils.file_utils.file_formats_model import FileExt, Format
+from kash.utils.text_handling.markdown_render import markdown_to_html
+from kash.utils.text_handling.markdown_utils import first_heading
 
 if TYPE_CHECKING:
     from kash.model.exec_model import ExecContext
@@ -359,15 +360,19 @@ class Item:
         cls,
         path: Path | str,
         item_type: ItemType | None = None,
+        *,
         title: str | None = None,
+        original_filename: str | None = None,
+        mime_type: MimeType | None = None,
     ) -> Item:
         """
         Create a resource Item for a file with a format inferred from the file extension
         or the content. Only sets basic metadata. Does not read the content. Will set
         `format` and `file_ext` if possible but will leave them as None if unrecognized.
+        If `mime_type` is provided, it can help determine the file extension.
         """
         from kash.file_storage.store_filenames import parse_item_filename
-        from kash.utils.file_utils.file_formats_model import detect_file_format
+        from kash.utils.file_utils.file_formats_model import choose_file_ext, detect_file_format
 
         # Will raise error for unrecognized file ext.
         _name, filename_item_type, format, file_ext = parse_item_filename(path)
@@ -380,12 +385,17 @@ class Item:
             item_type = (
                 ItemType.doc if format and format.supports_frontmatter else ItemType.resource
             )
+        # Do our best to determine a good file extension if it's not already on the filename.
+        if not file_ext and mime_type:
+            file_ext = choose_file_ext(path, mime_type)
+
         item = cls(
             type=item_type,
             title=title,
             file_ext=file_ext,
             format=format,
             external_path=str(path),
+            original_filename=original_filename,
         )
 
         # Update modified time from the file system.
@@ -507,17 +517,43 @@ class Item:
 
         return item_dict
 
-    def display_title(self) -> str:
+    def filename_stem(self) -> str | None:
         """
-        A display title for this item. Same as abbrev_title() but will fall back
-        to the filename if it is available.
+        If the item has an existing or previous filename, return its stem,
+        for use in picking new filenames.
         """
-        display_title = self.title
-        if not display_title and self.store_path:
-            display_title = Path(self.store_path).name
-        if not display_title:
-            display_title = self.abbrev_title()
-        return display_title
+        from kash.file_storage.store_filenames import parse_item_filename
+
+        # Prefer original to external, e.g. if we know the original but the external might
+        # be a cache filename.
+        path = self.store_path or self.original_filename or self.external_path
+        if path:
+            path_name, _item_type, _format, _file_ext = parse_item_filename(Path(path).name)
+        else:
+            path_name = None
+        return path_name
+
+    def slug_name(self, max_len: int = SLUG_MAX_LEN, prefer_title: bool = False) -> str:
+        """
+        Get a readable slugified name for this item, either from a previous filename
+        or from slugifying the title or content. May not be unique.
+        """
+        filename_stem = self.filename_stem()
+        if filename_stem and not prefer_title:
+            return slugify_snake(filename_stem)
+        else:
+            return slugify_snake(self.abbrev_title(max_len=max_len, add_ops_suffix=True))
+
+    def default_filename(self) -> str:
+        """
+        Get the default filename for an item based on slugifying its title or other
+        metadata. May not be unique.
+        """
+        from kash.file_storage.store_filenames import join_suffix
+
+        slug = self.slug_name()
+        full_suffix = self.get_full_suffix()
+        return join_suffix(slug, full_suffix)
 
     def abbrev_title(
         self,
@@ -527,12 +563,10 @@ class Item:
         pull_body_heading: bool = False,
     ) -> str:
         """
-        Get or infer a title for this item, falling back to the filename, URL,
-        description, or finally body text.
-        Optionally, include the last operation as a parenthetical at the end of the title.
+        Get or infer a title for this item, falling back to the filename, URL, description, or
+        finally body text. Optionally, include the last operation as a parenthetical at the end
+        of the title. Will use "Untitled" if all else fails.
         """
-        from kash.file_storage.store_filenames import parse_item_filename
-
         # First special case: if we are pulling the title from the body header, check
         # that.
         if not self.title and pull_body_heading:
@@ -544,18 +578,12 @@ class Item:
         if not self.title and self.url:
             return abbrev_str(self.url, max_len)
 
-        # Special case for filenames with no title.
-        # Use stem to drop suffix like .resource.docx etc in a title.
-        path = self.store_path or self.external_path or self.original_filename
-        if path:
-            path_name, _item_type, _format, _file_ext = parse_item_filename(Path(path).name)
-        else:
-            path_name = None
+        filename_stem = self.filename_stem()
 
         # Use the title or the path if possible, falling back to description or even body text.
         title_raw_text = (
             self.title
-            or path_name
+            or filename_stem
             or self.description
             or (not self.is_binary and self.abbrev_body(max_len))
             or UNTITLED
@@ -586,6 +614,24 @@ class Item:
 
         return final_text
 
+    def display_title(self) -> str:
+        """
+        A display title for this item. Same as abbrev_title() but will fall back
+        to the filename if it is available.
+        """
+        display_title = self.title
+        if not display_title and self.store_path:
+            display_title = Path(self.store_path).name
+        if not display_title:
+            display_title = self.abbrev_title()
+        return display_title
+
+    def abbrev_description(self, max_len: int = 1000) -> str:
+        """
+        Get or infer description.
+        """
+        return abbrev_on_words(html_to_plaintext(self.description or self.body or ""), max_len)
+
     def body_heading(self) -> str | None:
         """
         Get the first h1 or h2 heading from the body text, if present.
@@ -620,21 +666,6 @@ class Item:
         """
         return bool(self.body and self.body.strip())
 
-    def slug_name(self, max_len: int = SLUG_MAX_LEN) -> str:
-        """
-        Get a readable slugified version of the title or filename or content
-        appropriate for this item. May not be unique.
-        """
-        title = self.abbrev_title(max_len=max_len, add_ops_suffix=True)
-        slug = slugify_snake(title)
-        return slug
-
-    def abbrev_description(self, max_len: int = 1000) -> str:
-        """
-        Get or infer description.
-        """
-        return abbrev_on_words(html_to_plaintext(self.description or self.body or ""), max_len)
-
     def read_as_config(self) -> Any:
         """
         If it is a config Item, return the parsed YAML.
@@ -653,8 +684,6 @@ class Item:
         """
         if self.file_ext:
             return self.file_ext
-        if self.is_binary and not self.file_ext:
-            raise ValueError(f"Binary Items must have a file extension: {self}")
         inferred_ext = self.format and self.format.file_ext
         if not inferred_ext:
             raise ValueError(f"Cannot infer file extension for Item: {self}")

kash/shell/ui/shell_results.py

@@ -1,5 +1,6 @@
 from typing import Any
 
+from prettyfmt import fmt_count_items
 from rich.box import SQUARE
 from rich.panel import Panel
 from rich.table import Table
@@ -10,7 +11,7 @@ from kash.config.text_styles import COLOR_SELECTION, STYLE_HINT
 from kash.exec.command_exec import run_command_or_action
 from kash.exec_model.shell_model import ShellResult
 from kash.shell.output.shell_output import PrintHooks, console_pager, cprint, print_result
-from kash.utils.common.format_utils import fmt_count_items, fmt_loc
+from kash.utils.common.format_utils import fmt_loc
 from kash.utils.errors import is_fatal
 from kash.workspaces import SelectionHistory
 

kash/utils/common/format_utils.py

@@ -4,7 +4,6 @@ from pathlib import Path
 
 from prettyfmt import fmt_path
 
-from kash.utils.common.inflection import plural
 from kash.utils.common.url import Locator, is_url
 
 
@@ -44,13 +43,6 @@ def fmt_loc(locator: str | Locator, resolve: bool = True) -> str:
         return fmt_path(locator, resolve=resolve)
 
 
-def fmt_count_items(count: int, name: str = "item") -> str:
-    """
-    Format a count and a name as a pluralized phrase, e.g. "1 item" or "2 items".
-    """
-    return f"{count} {plural(name, count)}"  # pyright: ignore
-
-
 ## Tests