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

kash/actions/core/minify_html.py

@@ -0,0 +1,41 @@
+from kash.exec import kash_action
+from kash.exec.preconditions import has_fullpage_html_body
+from kash.model import Format, Item, Param
+from kash.utils.errors import InvalidInput
+from kash.workspaces.workspaces import current_ws
+
+
+@kash_action(
+    precondition=has_fullpage_html_body,
+    params=(
+        Param("no_js_min", "Disable JS minification", bool),
+        Param("no_css_min", "Disable CSS minification", bool),
+    ),
+)
+def minify_html(item: Item) -> Item:
+    """
+    Minify an HTML item's content using [html-minifier-terser](https://github.com/terser/html-minifier-terser).
+
+    Also supports Tailwind CSS v4 compilation and inlining, if any Tailwind
+    CSS v4 CDN script tags are found.
+
+    The terser minification seems a bit slower but more robust than
+    [minify-html](https://github.com/wilsonzlin/minify-html).
+    """
+    from minify_tw_html import minify_tw_html
+
+    if not item.store_path:
+        raise InvalidInput(f"Missing store path: {item}")
+
+    ws = current_ws()
+    input_path = ws.base_dir / item.store_path
+
+    output_item = item.derived_copy(format=Format.html, body=None)
+    output_path = ws.target_path_for(output_item)
+
+    minify_tw_html(input_path, output_path)
+
+    output_item.body = output_path.read_text()
+    output_item.external_path = str(output_path)  # Indicate item is already saved.
+
+    return output_item

kash/commands/base/show_command.py

@@ -1,6 +1,7 @@
 from kash.config.logger import get_logger
 from kash.config.text_styles import STYLE_HINT
 from kash.exec import assemble_path_args, kash_command
+from kash.exec_model.shell_model import ShellResult
 from kash.model.paths_model import StorePath
 from kash.shell.output.shell_output import cprint
 from kash.shell.utils.native_utils import ViewMode, terminal_show_image, view_file_native
@@ -19,7 +20,8 @@ def show(
     thumbnail: bool = False,
     browser: bool = False,
     plain: bool = False,
-) -> None:
+    noselect: bool = False,
+) -> ShellResult:
     """
     Show the contents of a file if one is given, or the first file if multiple files
     are selected. Will try to use native apps or web browser to display the file if
@@ -33,6 +35,7 @@ def show(
     :param thumbnail: If there is a thumbnail image, show it too.
     :param browser: Force display with your default web browser.
     :param plain: Use plain view in the console (this is `bat`'s `plain` style).
+    :param noselect: Disable default behavior where `show` also will `select` the file.
     """
     view_mode = (
         ViewMode.console
@@ -63,9 +66,16 @@ def show(
             view_file_native(ws.base_dir / input_path, view_mode=view_mode, plain=plain)
         else:
             view_file_native(input_path, view_mode=view_mode, plain=plain)
+        if not noselect:
+            from kash.commands.workspace.selection_commands import select
+
+            select(input_path)
+            return ShellResult(show_selection=True)
     except (InvalidInput, InvalidState):
         if path:
             # If path is absolute or we couldbn't get a selection, just show the file.
             view_file_native(path, view_mode=view_mode)
         else:
             raise InvalidInput("No selection")
+
+    return ShellResult(show_selection=False)

kash/config/colors.py

@@ -139,14 +139,16 @@ web_light_translucent = SimpleNamespace(
     bg_header=hsl_to_hex("hsla(188, 42%, 70%, 0.2)"),
     bg_alt=hsl_to_hex("hsla(39, 24%, 90%, 0.3)"),
     bg_alt_solid=hsl_to_hex("hsla(39, 24%, 97%, 1)"),
+    bg_selected=hsl_to_hex("hsla(188, 44%, 94%, 0.95)"),
     text=hsl_to_hex("hsl(188, 39%, 11%)"),
     code=hsl_to_hex("hsl(44, 38%, 23%)"),
     border=hsl_to_hex("hsl(188, 8%, 50%)"),
     border_hint=hsl_to_hex("hsla(188, 8%, 72%, 0.3)"),
     border_accent=hsl_to_hex("hsla(305, 18%, 65%, 0.85)"),
     hover=hsl_to_hex("hsl(188, 12%, 84%)"),
-    hover_bg=hsl_to_hex("hsla(188, 12%, 94%, 0.8)"),
+    hover_bg=hsl_to_hex("hsla(188, 44%, 94%, 1)"),
     hint=hsl_to_hex("hsl(188, 11%, 65%)"),
+    hint_strong=hsl_to_hex("hsl(188, 11%, 46%)"),
     hint_gentle=hsl_to_hex("hsla(188, 11%, 65%, 0.2)"),
     tooltip_bg=hsl_to_hex("hsla(188, 6%, 37%, 0.7)"),
     popover_bg=hsl_to_hex("hsla(188, 6%, 37%, 0.7)"),
@@ -170,14 +172,16 @@ web_dark_translucent = SimpleNamespace(
     bg_header=hsl_to_hex("hsla(188, 42%, 20%, 0.3)"),
     bg_alt=hsl_to_hex("hsla(220, 14%, 12%, 0.5)"),
     bg_alt_solid=hsl_to_hex("hsl(220, 14%, 12%)"),
+    bg_selected=hsl_to_hex("hsla(188, 12%, 50%, 0.95)"),
     text=hsl_to_hex("hsl(188, 10%, 90%)"),
     code=hsl_to_hex("hsl(44, 38%, 72%)"),
     border=hsl_to_hex("hsl(188, 8%, 25%)"),
     border_hint=hsl_to_hex("hsla(188, 8%, 35%, 0.3)"),
     border_accent=hsl_to_hex("hsla(305, 30%, 55%, 0.85)"),
     hover=hsl_to_hex("hsl(188, 12%, 35%)"),
-    hover_bg=hsl_to_hex("hsla(188, 20%, 25%, 0.4)"),
+    hover_bg=hsl_to_hex("hsla(188, 12%, 40%, 0.95)"),
     hint=hsl_to_hex("hsl(188, 11%, 55%)"),
+    hint_strong=hsl_to_hex("hsl(188, 11%, 72%)"),
     hint_gentle=hsl_to_hex("hsla(188, 11%, 55%, 0.2)"),
     tooltip_bg=hsl_to_hex("hsla(188, 6%, 20%, 0.9)"),
     popover_bg=hsl_to_hex("hsla(188, 6%, 20%, 0.9)"),

kash/docs/markdown/topics/a1_what_is_kash.md

@@ -3,35 +3,64 @@
 > “*Simple should be simple.
 > Complex should be possible.*” —Alan Kay
 
-Kash (“Knowledge Agent SHell”) is an **interactive, AI-native command-line** shell for
-practical knowledge tasks.
+Kash (“Knowledge Agent SHell”) is an experiment in making software tasks more modular,
+exploratory, and flexible using Python and current AI tools.
+
+The philosophy behind kash is similar to Unix shell tools: simple commands that can be
+combined in flexible and powerful ways.
+It operates on "items" such as URLs, files, or Markdown notes within a workspace
+directory.
+
+You can use Kash as an **interactive, AI-native command-line** shell for practical
+knowledge tasks. It's also **a Python library** that lets you convert a simple Python
+function into a command and an MCP tool, so it integrates with other tools like
+Anthropic Desktop or Cursor.
+
+It's new and still has some rough edges, but it's now working well enough it is feeling
+quite powerful. It now serves as a replacement for my usual shell (previously bash or
+zsh). I use it routinely to remix, combine, and interactively explore and then gradually
+automate complex tasks by composing AI tools, APIs, and libraries.
+And last but not least, the same framework lets me build other tools (like
+[textpress](https://github.com/jlevy/textpress)).
 
-It's also **a Python library** that lets you convert a simple Python function into a
-command and an MCP tool, so it integrates with other tools like Anthropic Desktop or
-Cursor.
+And of course, kash can read its own functionality and enhance itself by writing new
+actions.
 
-You can think of it a kind of power-tool for technical users who want to use Python and
-APIs, a kind of hybrid between an AI assistant, a shell, and a developer tool like
-Cursor or Claude Code.
+### Kash Packages
 
-It's my attempt at finding a way to remix, combine, and interactively explore and then
-gradually automate complex tasks by composing AI tools, APIs, and libraries.
+The [kash-shell](https://github.com/jlevy/kash) package is the base package and includes
+the Python framework, a few core utilities, and the Kash command-line shell.
 
-And of course, kash can read its own functionality and enhance itself by writing new
-actions.
+Additional actions for handling more complex tasks like converting documents and
+transcribing, researching, or annotating videos, are in the
+[kash-docs](https://github.com/jlevy/kash-docs) and
+[kash-media](https://github.com/jlevy/kash-docs) packages, all available on PyPI and
+quick to install via uv.
 
 ### Key Concepts
 
-- **Actions:** The core of Kash are **Kash actions**. By decorating a Python function,
-  you can turn it into an action, which makes it more flexible and powerful, able to
-  work with file inputs stored and outputs in a given directory, also called a
-  **workspace**.
+- **Actions:** The core of Kash are **actions**. By decorating a Python function with
+  `@kash_action`, you can turn it into an action, which makes it more flexible and
+  powerful. It can then be used like a command line command as well as a Python function
+  or an MCP tool.
+
+- **Workspaces:** A key element of Kash is that it does most nontrivial work in the
+  context of a **workspace**. A workspace is just a directory of files that have a few
+  conventions to make it easier to maintain context and perform actions.
+  A bit like how Git repos work, it has a `.kash/` directory that holds metadata and
+  cached content. The rest can be anything, but is typically directories of resources
+  (like .docx or .pdf or links to web pages) or content, typically Markdown files with
+  YAML frontmatter. All text files use
+  [frontmatter-format](https://github.com/jlevy/frontmatter-format) so have easy-to-read
+  YAML metadata that includes not just title or description, but also the names of the
+  actions that created it.
 
 - **Compositionality:** An action is composable with other actions simply as a Python
-  function, so complex (like transcribing and annotating a video) actions can be built
-  from simpler actions (like downloading and caching a YouTube video, identifying the
-  speakers in a transcript, etc.). The goal is to reduce the "interstitial complexity"
-  of combining tools, so it's easy for you (or an LLM!) to combine tools in flexible and
+  function, so complex operations (for example, transcribing and annotating a video and
+  publishing it on a website) actions can be built from simpler actions (say downloading
+  and caching a YouTube video, identifying the speakers in a transcript, formatting it
+  as pretty HTML, etc.). The goal is to reduce the "interstitial complexity" of
+  combining tools, so it's easy for you (or an LLM!) to combine tools in flexible and
   powerful ways.
 
 - **Command-line usage:** In addition to using the function in other libraries and
@@ -40,9 +69,6 @@ actions.
   video. In kash you have **smart tab completions**, **Python expressions**, and an **LLM
   assistant** built into the shell.
 
-- **MCP support:** Finally, an action is also an **MCP tool server** so you can use it
-  in any MCP client, like Anthropic Desktop or Cursor.
-
 - **Support for any API:** Kash is tool agnostic and runs locally, on file inputs in
   simple formats, so you own and manage your data and workspaces however you like.
   You can use it with any models or APIs you like, and is already set up to use the APIs
@@ -51,6 +77,9 @@ actions.
   **Perplexity**, **Firecrawl**, **Exa**, and any Python libraries.
   There is also some experimental support for **LlamaIndex** and **ChromaDB**.
 
+- **MCP support:** Finally, an action is also an **MCP tool server** so you can use it
+  in any MCP client, like Anthropic Desktop or Cursor.
+
 ### What Can Kash Do?
 
 You can use kash actions to do deep research, transcribe videos, summarize and organize

kash/docs/markdown/topics/a2_installation.md

@@ -2,9 +2,9 @@
 
 ### Running the Kash Shell
 
-Kash offers a shell environment based on [xonsh](https://xon.sh/) augmented with an LLM
-assistant and a variety of other enhanced commands and customizations.
-If you've used a bash or Python shell before, xonsh is very intuitive.
+Kash offers a shell environment based on [xonsh](https://xon.sh/) augmented with a bunch
+of enhanced commands and customizations.
+If you've used a bash or Python shell before, it should be very intuitive.
 
 Within the kash shell, you get a full environment with all actions and commands.
 You also get intelligent auto-complete, a built-in assistant to help you perform tasks,
@@ -38,30 +38,17 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
    Kash is easiest to use via [**uv**](https://docs.astral.sh/uv/), the new package
    manager for Python. `uv` replaces traditional use of `pyenv`, `pipx`, `poetry`, `pip`,
    etc. Installing `uv` also ensures you get a compatible version of Python.
-
-   If you don't have `uv` installed, a quick way to install it is:
-
+   See [uv's docs](https://docs.astral.sh/uv/getting-started/installation/) for other
+   installation methods and platforms.
+   Usually you just want to run:
    ```shell
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
 
-   For macOS, you prefer [brew](https://brew.sh/) you can install or upgrade uv with:
-
-   ```shell
-   brew update
-   brew install uv
-   ```
-   See [uv's docs](https://docs.astral.sh/uv/getting-started/installation/) for other
-   installation methods and platforms.
-
 2. **Install additional command-line tools:**
 
    In addition to Python, it's highly recommended to install a few other dependencies to
-   make more tools and commands work: `ripgrep` (for search), `bat` (for prettier file
-   display), `eza` (a much improved version of `ls`), `hexyl` (a much improved hex
-   viewer), `imagemagick` (for image display in modern terminals), `libmagic` (for file
-   type detection), `ffmpeg` (for audio and video conversions)
-
+   make more tools and commands work.
    For macOS, you can again use brew:
 
    ```shell
@@ -82,22 +69,22 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
 
    For Windows or other platforms, see the uv instructions.
 
+   Kash auto-detects and uses `ripgrep` (for search), `bat` (for prettier file display),
+   `eza` (a much improved version of `ls`), `hexyl` (a much improved hex viewer),
+   `imagemagick` (for image display in modern terminals), `libmagic` (for file type
+   detection), `ffmpeg` (for audio and video conversions)
+
 3. **Install kash or a kash kit:**
 
+   For a more meaningful demo, use an enhanced version of kash that also has various
+   media tools (like yt-dlp and Deepgram support):
+
    ```shell
-   uv tool install kash-media --python=3.13
+   uv tool install kash-media --upgrade --python=3.13
    ```
 
    Other versions of Python should work but 3.13 is recommended.
-   For a setup without the media tools, use `kash-shell` instead.
-
-   If you've installed an older version and want to be sure you have the latest shell,
-   you may want to add `--upgrade --force` to be sure you get the latest version of the
-   kit.
-
-   ```shell
-   uv tool install kash-media --python=3.13 --upgrade --force 
-   ```
+   For a setup without the media tools, just install `kash-shell` instead.
 
 4. **Set up API keys:**
 

kash/docs/markdown/topics/a3_getting_started.md

@@ -15,25 +15,11 @@ Type `help` for the full documentation.
 The simplest way to illustrate how to use kash is by example.
 You can go through the commands below a few at a time, trying each one.
 
-This is a "real" example that uses a bunch of libraries.
+This is a "real" example that uses ffmpeg and a few other libraries.
 So to get it to work you must install not just the main shell but the kash "media kit"
 with extra dependencies.
-
-You need the following tools:
-
-```shell
-# On MacOS:
-brew install ripgrep bat eza hexyl imagemagick libmagic ffmpeg 
-# On Linux:
-apt install ripgrep bat eza hexyl imagemagick libmagic ffmpeg
-```
-
-Then install the `kash-media`, which includes kash-shell and many other libs like yt-dlp
-for YouTube handling:
-
-```shell
-uv tool install kash-media
-```
+This is discussed in [the installation instructions](#installation-steps).
+If you don't have these already installed, you can add these tools:
 
 Then run `kash` to start.
 
@@ -152,7 +138,7 @@ show_webpage
 show_webpage --help
 
 # And you can actually how this works by looking at its source:
-source_code show_webpage
+show_webpage --show_source
 
 # What if something isn't working right?
 # Sometimes we may want to browse more detailed system logs:
@@ -171,7 +157,7 @@ transcribe_format https://www.youtube.com/watch?v=_8djNYprRDI
 
 # Getting a little fancier, this one adds little paragraph annotations and
 # a nicer summary at the top:
-transcribe_annotate_summarize https://www.youtube.com/watch?v=_8djNYprRDI
+transcribe_annotate https://www.youtube.com/watch?v=_8djNYprRDI
 
 show_webpage
 ```

kash/exec/action_exec.py

@@ -102,7 +102,7 @@ def log_action(action: Action, action_input: ActionInput, operation: Operation):
     """
     PrintHooks.before_log_action_run()
     log.message("%s Action: `%s`", EMOJI_START, action.name)
-    log.message("Running: `%s`", operation.command_line(with_options=True))
+    log.info("Running: `%s`", operation.command_line(with_options=True))
     if len(action.param_value_summary()) > 0:
         log.message("Parameters:\n%s", action.param_value_summary_str())
     log.info("Operation is: %s", operation)

kash/exec/fetch_url_metadata.py

@@ -5,6 +5,7 @@ from kash.model.items_model import Item, ItemType
 from kash.model.paths_model import StorePath
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, is_url
+from kash.utils.common.url_slice import add_slice_to_url, parse_url_slice
 from kash.utils.errors import InvalidInput
 
 log = get_logger(__name__)
@@ -55,6 +56,14 @@ def fetch_url_item_metadata(item: Item, refetch: bool = False) -> Item:
     media_metadata = get_media_metadata(url)
     if media_metadata:
         fetched_item = Item.from_media_metadata(media_metadata)
+        # Preserve and canonicalize any slice suffix on the URL.
+        _base_url, slice = parse_url_slice(item.url)
+        if slice:
+            new_url = add_slice_to_url(media_metadata.url, slice)
+            if new_url != item.url:
+                log.message("Updated URL from metadata and added slice: %s", new_url)
+            fetched_item.url = new_url
+
         fetched_item = item.merged_copy(fetched_item)
     else:
         page_data = fetch_extract(url, refetch=refetch)

kash/exec/precondition_registry.py

@@ -39,7 +39,7 @@ def kash_precondition(func: Callable[[Item], bool]) -> Precondition:
 
 def get_all_preconditions() -> dict[str, Precondition]:
     """
-    Returns a copy of all registered preconditions.
+    Returns a copy of all registered preconditions (in alphabetical order).
     """
-    # Return a copy for safety.
-    return dict(_preconditions.copy())
+    # Return a copy for safety, sorted by key.
+    return dict(sorted(_preconditions.copy().items()))

kash/file_storage/file_store.py

@@ -83,6 +83,11 @@ class FileStore(Workspace):
     def base_dir(self) -> Path:
         return self.base_dir_path
 
+    @property
+    @override
+    def assets_dir(self) -> Path:
+        return self.base_dir / "assets"
+
     @synchronized
     @log_calls(level="warning", if_slower_than=2.0)
     def reload(self, auto_init: bool = True):
@@ -340,6 +345,18 @@ class FileStore(Workspace):
 
             return StorePath(store_path), old_store_path
 
+    def target_path_for(self, item: Item) -> Path:
+        """
+        Get an the absolute path for an item. Use this if you need to work around the
+        usual save mechanism and write directly to the store yourself, at the location
+        the item usually would be saved.
+
+        If you write to this path, then set the item's `external_path` to indicate it's
+        already saved.
+        """
+        store_path, _old_store_path = self.store_path_for(item)
+        return self.base_dir / store_path
+
     def _tmp_path_for(self, item: Item) -> StorePath:
         """
         Find a path for an item in the tmp directory.
@@ -468,7 +485,7 @@ class FileStore(Workspace):
         item.store_path = str(store_path)
         self._id_index_item(store_path)
 
-        log.message("%s Saved item:\n%s", EMOJI_SAVED, fmt_lines([fmt_loc(store_path)]))
+        log.message("%s Saved item: %s", EMOJI_SAVED, fmt_loc(store_path))
         return store_path
 
     @log_calls(level="debug")

kash/llm_utils/llm_features.py

@@ -56,13 +56,17 @@ FEATURES = {
 }
 
 preferred_llms: list[LLMName] = [
+    LLM.o4_mini,
+    LLM.o3,
     LLM.o3_mini,
     LLM.o1_mini,
     LLM.o1,
     LLM.gpt_4o_mini,
     LLM.gpt_4o,
     LLM.gpt_4,
+    LLM.claude_4_sonnet,
+    LLM.claude_4_opus,
     LLM.claude_3_7_sonnet,
-    LLM.claude_3_5_sonnet,
     LLM.claude_3_5_haiku,
+    LLM.gemini_2_5_pro_preview_05_06,
 ]

kash/llm_utils/llms.py

@@ -13,32 +13,42 @@ class LLM(LLMName, Enum):
     """
 
     # https://platform.openai.com/docs/models
-    o1_mini = LLMName("o1-mini")
-    o1 = LLMName("o1")
+    o4_mini = LLMName("o4-mini")
     o3 = LLMName("o3")
     o3_mini = LLMName("o3-mini")
-    o4_mini = LLMName("o4-mini")
+    o1 = LLMName("o1")
+    o1_mini = LLMName("o1-mini")
+    o1_pro = LLMName("o1-pro")
     o1_preview = LLMName("o1-preview")
-    gpt_4o_mini = LLMName("gpt-4o-mini")
+    gpt_4_1 = LLMName("gpt-4.1")
     gpt_4o = LLMName("gpt-4o")
+    gpt_4o_mini = LLMName("gpt-4o-mini")
     gpt_4 = LLMName("gpt-4")
-    gpt_4_1 = LLMName("gpt-4.1")
+
     gpt_4_1_mini = LLMName("gpt-4.1-mini")
     gpt_4_1_nano = LLMName("gpt-4.1-nano")
 
     # https://docs.anthropic.com/en/docs/about-claude/models/all-models
+    claude_4_opus = LLMName("claude-opus-4-20250514")
+    claude_4_sonnet = LLMName("claude-sonnet-4-20250514")
     claude_3_7_sonnet = LLMName("claude-3-7-sonnet-latest")
-    claude_3_5_sonnet = LLMName("claude-3-5-sonnet-latest")
     claude_3_5_haiku = LLMName("claude-3-5-haiku-latest")
 
     # https://ai.google.dev/gemini-api/docs/models
-    gemini_2_5_pro_exp_03_25 = LLMName("gemini/gemini-2.5-pro-exp-03-25")
+    gemini_2_5_pro_preview_06_05 = LLMName("gemini/gemini-2.5-pro-preview-06-05")
+    gemini_2_5_pro_preview_05_06 = LLMName("gemini/gemini-2.5-pro-preview-05-06")
+    gemini_2_5_pro_preview_03_25 = LLMName("gemini/gemini-2.5-pro-preview-03-25")
+    gemini_2_5_flash_preview = LLMName("gemini-2.5-flash-preview-05-20")
     gemini_2_0_flash = LLMName("gemini/gemini-2_0-flash")
     gemini_2_0_flash_lite = LLMName("gemini/gemini-2.0-flash-lite")
     gemini_2_0_pro_exp_02_05 = LLMName("gemini/gemini-2.0-pro-exp-02-05")
 
     # https://docs.x.ai/docs/models
-    xai_grok_2 = LLMName("xai/grok-2-latest")
+    xai_grok_3 = LLMName("xai/grok-3")
+    xai_grok_3_fast = LLMName("xai/grok-3-fast")
+    xai_grok_3_mini = LLMName("xai/grok-3-mini")
+    xai_grok_3_mini_fast = LLMName("xai/grok-3-mini-fast")
+    xai_grok_2 = LLMName("xai/grok-2")
 
     # https://api-docs.deepseek.com/quick_start/pricing
     deepseek_chat = LLMName("deepseek/deepseek-chat")