kash-shell 0.3.20__py3-none-any.whl → 0.3.22__py3-none-any.whl

kash/actions/core/markdownify_html.py

@@ -1,9 +1,12 @@
+from prettyfmt import abbrev_on_words
+
 from kash.config.logger import get_logger
 from kash.exec import kash_action
 from kash.exec.preconditions import has_html_body, is_url_resource
 from kash.exec.runtime_settings import current_runtime_settings
 from kash.model import Format, Item
 from kash.model.items_model import ItemType
+from kash.utils.text_handling.markdown_utils import first_heading
 from kash.utils.text_handling.markdownify_utils import markdownify_custom
 from kash.web_content.file_cache_utils import get_url_html
 from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
@@ -25,6 +28,14 @@ def markdownify_html(item: Item) -> Item:
     assert page_data.clean_html
     markdown_content = markdownify_custom(page_data.clean_html)
 
+    # Sometimes readability doesn't include the title, in which case we add it.
+    first_h1 = first_heading(markdown_content, allowed_tags=("h1",))
+    title = page_data.title and abbrev_on_words(page_data.title.strip(), 80)
+    if not first_h1 and title:
+        log.message(f"No h1 found, inserting h1: {title}")
+        # Insert a h1 at the top of the document
+        markdown_content = f"# {title}\n\n{markdown_content}"
+
     output_item = item.derived_copy(
         type=ItemType.doc, format=Format.markdown, body=markdown_content
     )

kash/actions/core/tabbed_webpage_generate.py

@@ -1,6 +1,6 @@
 from kash.config.logger import get_logger
 from kash.exec import kash_action
-from kash.exec.preconditions import is_config
+from kash.exec.preconditions import is_data
 from kash.model import ONE_ARG, ActionInput, ActionResult, FileExt, Format, Item, ItemType, Param
 from kash.web_gen import tabbed_webpage
 
@@ -9,7 +9,7 @@ log = get_logger(__name__)
 
 @kash_action(
     expected_args=ONE_ARG,
-    precondition=is_config,
+    precondition=is_data,
     params=(Param("add_title", "Add a title to the page body.", type=bool),),
 )
 def tabbed_webpage_generate(input: ActionInput, add_title: bool = False) -> ActionResult:

kash/commands/help/assistant_commands.py

@@ -1,8 +1,6 @@
-from rich import get_console
-
 from kash.commands.base.basic_file_commands import trash
 from kash.commands.workspace.selection_commands import select
-from kash.config.logger import get_logger
+from kash.config.logger import get_console, get_logger
 from kash.config.text_styles import PROMPT_ASSIST, SPINNER
 from kash.docs.all_docs import DocSelection
 from kash.exec import kash_command
@@ -45,7 +43,7 @@ def assist(
             help()
             return
 
-    with get_console().status("Thinking…", spinner=SPINNER):
+    with get_console().status("Thinking…", spinner=SPINNER):  # noqa: F821
         shell_context_assistance(input, model=model, assistance_type=type)
 
 

kash/commands/help/logo.py

@@ -2,7 +2,8 @@ import re
 from pathlib import Path
 
 from rich.box import SQUARE
-from rich.console import Group
+from rich.console import Group, RenderableType
+from rich.padding import Padding
 from rich.panel import Panel
 from rich.text import Text
 
@@ -62,7 +63,13 @@ def color_logo() -> Group:
     )
 
 
-def branded_box(content: Group | None, version: str | None = None) -> Panel:
+def simple_box(content: RenderableType) -> Panel:
+    return Panel(
+        content, border_style=COLOR_HINT, padding=(0, 1), width=CONSOLE_WRAP_WIDTH, box=SQUARE
+    )
+
+
+def logo_box(content: Group | None = None) -> Padding:
     panel_width = CONSOLE_WRAP_WIDTH
 
     logo_lines = LOGO_LARGE.split("\n")
@@ -70,29 +77,17 @@ def branded_box(content: Group | None, version: str | None = None) -> Panel:
     tagline_offset = (panel_width - 4 - len(TAGLINE_STYLED)) // 2
 
     colored_lines = [logo_colorize_line(line, " ", rest_offset) for line in logo_lines]
-    header = None
-    if version:
-        footer = Text(version, style=COLOR_HINT, justify="right")
-    else:
-        footer = None
 
     body = ["", content] if content else []
 
-    return Panel(
+    return Padding(
         Group(
             Text.assemble(" " * tagline_offset, LOGO_SPACER),
             *colored_lines,
             Text.assemble(" " * tagline_offset, TAGLINE_STYLED),
             *body,
         ),
-        title=header,
-        title_align="center",
-        subtitle=footer,
-        subtitle_align="right",
-        border_style=COLOR_HINT,
-        padding=(0, 1),
-        width=panel_width,
-        box=SQUARE,
+        pad=(1, 1),
     )
 
 
@@ -101,7 +96,7 @@ def kash_logo(box: bool = False, svg_out: str | None = None, html_out: str | Non
     """
     Show the kash logo.
     """
-    logo = branded_box(None) if box else color_logo()
+    logo = logo_box(None) if box else color_logo()
 
     cprint(logo)
 

kash/commands/help/welcome.py

@@ -2,7 +2,7 @@ from rich.box import SQUARE
 from rich.console import Group
 from rich.panel import Panel
 
-from kash.commands.help.logo import branded_box
+from kash.commands.help.logo import logo_box, simple_box
 from kash.config.text_styles import (
     COLOR_HINT,
 )
@@ -20,14 +20,15 @@ def welcome() -> None:
     """
 
     help_topics = all_docs.help_topics
-    version = get_full_version_name()
+
     # Create header with logo and right-justified version
 
     PrintHooks.before_welcome()
+    cprint(logo_box())
     cprint(
-        branded_box(
+        simple_box(
             Group(Markdown(help_topics.welcome)),
-            version,
         )
     )
     cprint(Panel(Markdown(help_topics.warning), box=SQUARE, border_style=COLOR_HINT))
+    cprint("%s", get_full_version_name())

kash/config/colors.py

@@ -139,14 +139,15 @@ 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)"),
+    bg_meta_solid=hsl_to_hex("hsla(39, 24%, 94%, 1)"),
+    bg_selected=hsl_to_hex("hsla(188, 21%, 94%, 0.9)"),
     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, 44%, 94%, 1)"),
+    hover_bg=hsl_to_hex("hsla(188, 18%, 97%, 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)"),
@@ -165,14 +166,15 @@ web_light_translucent = SimpleNamespace(
 web_dark_translucent = SimpleNamespace(
     primary=hsl_to_hex("hsl(188, 40%, 62%)"),
     primary_light=hsl_to_hex("hsl(188, 50%, 72%)"),
-    secondary=hsl_to_hex("hsl(188, 12%, 65%)"),
-    tertiary=hsl_to_hex("hsl(188, 7%, 40%)"),
+    secondary=hsl_to_hex("hsl(188, 12%, 70%)"),
+    tertiary=hsl_to_hex("hsl(188, 7%, 45%)"),
     bg=hsl_to_hex("hsla(220, 14%, 7%, 0.95)"),
     bg_solid=hsl_to_hex("hsl(220, 14%, 7%)"),
     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)"),
+    bg_alt_solid=hsl_to_hex("hsl(220, 15%, 16%)"),
+    bg_meta_solid=hsl_to_hex("hsl(220, 14%, 25%)"),
+    bg_selected=hsl_to_hex("hsla(188, 13%, 33%, 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%)"),

kash/config/text_styles.py

@@ -277,6 +277,8 @@ EMOJI_HELP = "?"
 
 EMOJI_ACTION = "⛭"
 
+EMOJI_TASK = "⚒"
+
 EMOJI_COMMAND = "⧁"  # More ideas: ⦿⧁⧀⦿⦾⟐⦊⟡
 
 EMOJI_SHELL = "⦊"

kash/docs/markdown/topics/b1_kash_overview.md

@@ -165,48 +165,37 @@ works on readable text such as Markdown.
 This catches errors and allows you to find actions that might apply to a given selected
 set of items using `suggest_actions`.
 
-### Programmatic Use
-
-Since commands and actions are really just Python functions.
-
-### Useful Features
-
-Kash makes a few kinds of messy text manipulations easier:
-
-- Reusable LLM actions: A common kind of action is to invoke an LLM (like GPT-4o or o1)
-  on a text item, with a given system and user prompt template.
-  New LLM actions can be added with a few lines of Python by subclassing an action base
-  class, typically `Action`, `CachedItemAction` (for any action that doesn't need to be
-  rerun if it has the same single output), `CachedLLMAction` (if it also is performing
-  an LLM-based transform), or `ChunkedLLMAction` (if it will be processing a document
-  broken into <div class="chunk"> elements).
-
-- Sliding window transformations: LLMs can have trouble processing large inputs, not
-  just because of context window and because they may make more mistakes when making
-  lots of changes at once.
-  Kash supports running actions in a sliding window across the document, then stitching
-  the results back together when done.
-
-- Checking and enforcing changes: LLMs do not reliably do what they are asked to do.
-  So a key part of making them useful is to save outputs at each step of the way and
-  have a way to review their outputs or provide guardrails on what they can do with
-  content.
-
-- Fine-grainded diffs with word tokens: Documents can be represented at the word level,
-  using “word tokens” to represent words and normalized whitespace (word, sentence, and
-  paragraph breaks, but not line breaks).
-  This allows diffs of similar documents regardless of formatting.
-  For example, it is possible to ask an LLM only to add paragraph breaks, then drop any
-  other changes it makes to other words.
-  You can use this intelligent matching of words to “backfill” specific content from one
-  doc into an edited document, such as pulling timestamps from a full transcript back
-  into an edited transcript or summary.
-
-- Paragraph and sentence operations: A lot of operations within actions should be done
-  in chunks at the paragraph or sentence level.
-  Kash offers simple tools to subdivide documents into paragraphs and sentences and
-  these can be used together with sliding windows to process large documents.
-
-In addition, there are built-in kash commands that are part of the kash tool itself.
-These allow you to list items in the workspace, see or change the current selection,
-archive items, view logs, etc.
+### Programmatic Usage
+
+Kash can be used entirely programmatically, so that actions are called just like
+functions from Python, but the additional functionality of the items model, saving files
+to a workspace, and so on, are all automatic.
+
+This means you can use Kash to build your own CLI apps much more quickly.
+
+For an example of this, see [textpress](https://github.com/jlevy/textpress), which wraps
+quite a few kash actions to allow clean publishing of docx or PDF files on
+[textpress.md](https://textpress.md/).
+
+### Utilities and Supporting Libraries
+
+Kash includes a number of utility libraries to help with common tasks, either in the
+base `kash-shell` package or or smaller dependencies:
+
+- See [frontmatter-format](https://github.com/jlevy/frontmatter-format) for the spec and
+  implementation we use of frontmatter YAML format.
+
+- See
+  [utils/file_utils](https://github.com/jlevy/kash/tree/main/src/kash/utils/file_utils)
+  for file format detection, conversion, filename handling, etc.
+
+- See [chopdiff](https://github.com/jlevy/chopdiff) for a simple text doc data model
+  that includes sentences and paragraphs and fairly advanced diffing, filtered diffing,
+  and windowed transformations of text via LLM calls.
+
+- See [clideps](https://github.com/jlevy/clideps) for utilities for helping with dot-env
+  files, API key setup, and dependency checks.
+
+- See [utils/common](https://github.com/jlevy/kash/tree/main/src/kash/utils/common) the
+  rest of [utils/](https://github.com/jlevy/kash/tree/main/src/kash/utils) for a variety
+  of other general utilities.

kash/docs/markdown/warning.md

@@ -1,3 +1,3 @@
-**Important:** *Kash will not execute commands without confirmation.
-But this is a shell so commands can be destructive or dangerous.
-Review commands carefully!*
+**Important:** This is a shell.
+Commands can be destructive.
+Review commands carefully!

kash/docs/markdown/welcome.md

@@ -1,5 +1,6 @@
-**Welcome to kash!** Use `help` for the manual and full list of available commands.
+**Welcome to Kash!**
 
+Use `help` for the manual and full list of available commands.
 Press **tab** for contextual autocomplete of commands, questions, actions, and files.
 You may simply ask a question and the kash assistant will help you.
 Press **space** (or type **?**), then write your question or request.

kash/exec/action_decorators.py

@@ -105,7 +105,10 @@ def kash_action_class(cls: type[A]) -> type[A]:
 
 
 def _register_dynamic_action(
-    action_cls: type[A], action_name: str, action_description: str, source_path: Path | None
+    action_cls: type[A],
+    action_name: str,
+    action_description: str,
+    source_path: Path | None,
 ) -> type[A]:
     # Set class fields for name and description for convenience.
     action_cls.name = action_name
@@ -206,6 +209,7 @@ def kash_action(
     run_per_item: bool | None = None,
     uses_selection: bool = True,
     interactive_input: bool = False,
+    live_output: bool = False,
     mcp_tool: bool = False,
     title_template: TitleTemplate = TitleTemplate("{title}"),
     llm_options: LLMOptions = LLMOptions(),
@@ -235,13 +239,17 @@ def kash_action(
     def decorator(orig_func: AF) -> AF:
         if hasattr(orig_func, "__action_class__"):
             log.warning(
-                "Function `%s` is already decorated with `@kash_action`", orig_func.__name__
+                "Function `%s` is already decorated with `@kash_action`",
+                orig_func.__name__,
             )
             return orig_func
 
         # Inspect and sanity check the formal params.
         func_params = inspect_function_params(orig_func)
-        if len(func_params) == 0 or func_params[0].effective_type not in (ActionInput, Item):
+        if len(func_params) == 0 or func_params[0].effective_type not in (
+            ActionInput,
+            Item,
+        ):
             raise InvalidDefinition(
                 f"Decorator `@kash_action` requires exactly one positional parameter, "
                 f"`input` of type `ActionInput` or `Item` on function `{orig_func.__name__}` but "
@@ -311,6 +319,7 @@ def kash_action(
                 self.uses_selection = uses_selection
                 self.output_type = output_type
                 self.interactive_input = interactive_input
+                self.live_output = live_output
                 self.mcp_tool = mcp_tool
                 self.title_template = title_template
                 self.llm_options = llm_options
@@ -332,8 +341,14 @@ def kash_action(
                         kw_args[fp.name] = self.get_param(fp.name)
 
                 if self.params:
-                    log.info("Action function param declarations:\n%s", fmt_lines(self.params))
-                    log.info("Action function param values:\n%s", self.param_value_summary_str())
+                    log.info(
+                        "Action function param declarations:\n%s",
+                        fmt_lines(self.params),
+                    )
+                    log.info(
+                        "Action function param values:\n%s",
+                        self.param_value_summary_str(),
+                    )
                 else:
                     log.info("Action function has no declared params")
 

kash/exec/fetch_url_items.py

@@ -48,9 +48,10 @@ def fetch_url_item_content(item: Item, *, save_content: bool = True, refetch: bo
     from kash.workspaces import current_ws
 
     ws = current_ws()
-    if not refetch and item.title and item.description:
+    if not refetch and item.title and item.description and item.body:
         log.message(
-            "Already have title and description, will not fetch metadata: %s", item.fmt_loc()
+            "Already have title, description, and body, will not fetch: %s",
+            item.fmt_loc(),
         )
         return item
 
@@ -100,10 +101,11 @@ def fetch_url_item_content(item: Item, *, save_content: bool = True, refetch: bo
     # Now save the updated URL item and also the content item if we have one.
     ws.save(url_item)
     assert url_item.store_path
-    log.debug("Saved URL item: %s", url_item.fmt_loc())
     if content_item:
         ws.save(content_item)
         assert content_item.store_path
-        log.debug("Saved content item: %s", content_item.fmt_loc())
+        log.info("Saved content item: %s", content_item.fmt_loc())
+    else:
+        log.info("Saved URL item: %s", url_item.fmt_loc())
 
     return content_item or url_item

kash/exec/llm_transforms.py

@@ -68,7 +68,7 @@ def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: boo
             diff_filter=options.diff_filter,
         ).reassemble()
     else:
-        log.message(
+        log.info(
             "Running simple LLM transform action %s with model %s",
             options.op_name,
             options.model.litellm_name,

kash/exec/preconditions.py

@@ -48,8 +48,13 @@ def is_concept(item: Item) -> bool:
 
 
 @kash_precondition
-def is_config(item: Item) -> bool:
-    return item.type == ItemType.config
+def is_data(item: Item) -> bool:
+    return item.type == ItemType.data
+
+
+@kash_precondition
+def is_table(item: Item) -> bool:
+    return item.type == ItemType.table
 
 
 @kash_precondition

kash/exec/shell_callable_action.py

@@ -56,7 +56,7 @@ class ShellCallableAction:
 
             log.info("Action shell args: %s", shell_args)
             explicit_values = RawParamValues(shell_args.options)
-            if not action.interactive_input:
+            if not action.interactive_input and not action.live_output:
                 with get_console().status(f"Running action {action.name}…", spinner=SPINNER):
                     result = run_action_with_shell_context(
                         action_cls,

kash/llm_utils/llm_completion.py

@@ -173,7 +173,7 @@ def llm_template_completion(
     )
 
     if check_no_results and is_no_results(result.content):
-        log.message("No results for LLM transform, will ignore: %r", result.content)
+        log.info("No results for LLM transform, will ignore: %r", result.content)
         result.content = ""
 
     return result

kash/model/actions_model.py

@@ -270,6 +270,12 @@ class Action(ABC):
     Does this action ask for input interactively?
     """
 
+    live_output: bool = False
+    """
+    Does this action have live output (e.g., progress bars, spinners)?
+    If True, the shell should not show its own status spinner.
+    """
+
     mcp_tool: bool = False
     """
     If True, this action is published as an MCP tool.

kash/model/items_model.py

@@ -55,7 +55,8 @@ class ItemType(Enum):
     concept = "concept"
     resource = "resource"
     asset = "asset"
-    config = "config"
+    data = "data"
+    table = "table"
     export = "export"
     chat = "chat"
     extension = "extension"
@@ -86,7 +87,9 @@ class ItemType(Enum):
             Format.diff: ItemType.doc,
             Format.python: ItemType.extension,
             Format.json: ItemType.doc,
-            Format.csv: ItemType.doc,
+            Format.csv: ItemType.table,
+            Format.xlsx: ItemType.table,
+            Format.npz: ItemType.table,
             Format.log: ItemType.log,
             Format.pdf: ItemType.resource,
             Format.jpeg: ItemType.asset,
@@ -646,7 +649,7 @@ class Item:
         body_text = abbrev_str(self.body_text(), max_len)
 
         # Just for aesthetics, especially for titles of chat files.
-        if self.type in [ItemType.chat, ItemType.config] or self.format == Format.yaml:
+        if self.type in [ItemType.chat, ItemType.data] or self.format == Format.yaml:
             try:
                 yaml_obj = list(new_yaml().load_all(self.body_text()))
                 if len(yaml_obj) > 0:
@@ -663,16 +666,16 @@ class Item:
         """
         return bool(self.body and self.body.strip())
 
-    def read_as_config(self) -> Any:
+    def read_as_data(self) -> Any:
         """
-        If it is a config Item, return the parsed YAML.
+        If it is a data Item, return the parsed YAML.
         """
-        if not self.type == ItemType.config:
-            raise FileFormatError(f"Item is not a config: {self}")
+        if not self.type == ItemType.data:
+            raise FileFormatError(f"Item is not a data item: {self}")
         if not self.body:
-            raise FileFormatError(f"Config item has no body: {self}")
+            raise FileFormatError(f"Data item has no body: {self}")
         if self.format != Format.yaml:
-            raise FileFormatError(f"Config item is not YAML: {self.format}: {self}")
+            raise FileFormatError(f"Data item is not YAML: {self.format}: {self}")
         return from_yaml_string(self.body)
 
     def get_filename(self) -> str | None:
@@ -709,8 +712,8 @@ class Item:
         elif self.type == ItemType.script:
             # Same for kash/xonsh scripts.
             return f"{self.type.value}.{FileExt.xsh.value}"
-        elif self.type == ItemType.export:
-            # For exports, skip the item type to keep it maximally compatible for external tools.
+        elif self.type in [ItemType.export, ItemType.data, ItemType.table]:
+            # For exports, data, and tables, skip the item type to keep it maximally compatible for external tools.
             return f"{self.get_file_ext().value}"
         else:
             return f"{self.type.value}.{self.get_file_ext().value}"

kash/shell/output/shell_output.py

@@ -4,7 +4,7 @@ Output to the shell UI. These are for user interaction, not logging.
 
 import contextvars
 from collections.abc import Callable
-from contextlib import contextmanager
+from contextlib import contextmanager, nullcontext
 from enum import Enum, auto
 
 import rich
@@ -28,6 +28,7 @@ from kash.config.text_styles import (
     STYLE_HINT,
 )
 from kash.shell.output.kmarkdown import KMarkdown
+from kash.utils.rich_custom.multitask_status import MultiTaskStatus, StatusSettings
 from kash.utils.rich_custom.rich_indent import Indent
 from kash.utils.rich_custom.rich_markdown_fork import Markdown
 
@@ -80,6 +81,24 @@ def console_pager(use_pager: bool = True):
     PrintHooks.after_pager()
 
 
+def multitask_status(
+    settings: StatusSettings | None = None, *, auto_summary: bool = True, enabled: bool = True
+) -> MultiTaskStatus | nullcontext:
+    """
+    Create a `MultiTaskStatus` context manager for displaying multiple task progress
+    using the global shell console. If disabled, returns a null context, so it's convenient
+    to disable status display.
+    """
+    if not enabled:
+        return nullcontext()
+
+    return MultiTaskStatus(
+        console=get_console(),
+        settings=settings,
+        auto_summary=auto_summary,
+    )
+
+
 null_style = rich.style.Style.null()