kash-shell 0.3.0__py3-none-any.whl

kash/__init__.py

@@ -0,0 +1,2 @@
+# This file is part of the namespace package
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

kash/__main__.py

@@ -0,0 +1,4 @@
+from kash.shell_main import main
+
+if __name__ == "__main__":
+    main()

kash/actions/__init__.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.config.settings import APP_NAME
+from kash.exec import import_action_subdirs
+from kash.utils.common.atomic_var import AtomicVar
+from kash.utils.common.import_utils import import_namespace_modules
+
+log = get_logger(__name__)
+
+# This hook can be used for auto-registering actions from any module.
+import_action_subdirs(["core", "meta"], __package__, Path(__file__).parent)
+
+
+@dataclass(frozen=True)
+class Kit:
+    name: str
+    full_module_name: str
+    path: Path | None
+
+
+_kits: AtomicVar[dict[str, Kit]] = AtomicVar(initial_value={})
+
+
+def get_loaded_kits() -> dict[str, Kit]:
+    """
+    Get all kits (modules within `kash.kits`) that have been loaded.
+    """
+    return _kits.copy()
+
+
+def load_kits() -> dict[str, Kit]:
+    """
+    Import all kits (modules within `kash.kits`) by inspecting the namespace.
+    """
+    kits_namespace = f"{APP_NAME}.kits"
+    new_kits = {}
+    try:
+        imported = import_namespace_modules(kits_namespace)
+        for name, module in imported.items():
+            new_kits[name] = Kit(
+                name,
+                module.__name__,
+                Path(module.__file__) if module.__file__ else None,
+            )
+    except ImportError:
+        log.info("No kits found in namespace `%s`", kits_namespace)
+
+    _kits.update(lambda kits: {**kits, **new_kits})
+
+    return new_kits
+
+
+load_kits()

kash/actions/core/assistant_chat.py

@@ -0,0 +1,45 @@
+from kash.exec import kash_action
+from kash.exec.preconditions import is_chat
+from kash.form_input.prompt_input import prompt_simple_string
+from kash.help.assistant import assistant_chat_history, shell_context_assistance
+from kash.help.assistant_output import print_assistant_heading
+from kash.llm_utils.language_models import LLM, LLMName
+from kash.model import NO_ARGS, ActionInput, ActionResult, common_params
+from kash.shell.output.shell_output import PrintHooks, Wrap, print_response
+
+
+@kash_action(
+    expected_args=NO_ARGS,
+    interactive_input=True,
+    cacheable=False,
+    precondition=is_chat,
+    params=common_params("model"),
+)
+def assistant_chat(input: ActionInput, model: LLMName = LLM.default_careful) -> ActionResult:
+    """
+    Chat with the kash assistant. This is just the same as typing on the command line,
+    but with a chat session.
+    """
+    chat_history = assistant_chat_history(
+        include_system_message=True, is_structured=False, skip_api_docs=False
+    )
+    PrintHooks.spacer()
+    print_assistant_heading(model)
+    print_response(
+        f"History of {chat_history.size_summary()}.\nPress enter (or type `exit`) to end chat.",
+        text_wrap=Wrap.NONE,
+    )
+
+    while True:
+        try:
+            user_message = prompt_simple_string(f"assistant/{model.litellm_name}")
+        except KeyboardInterrupt:
+            break
+
+        user_message = user_message.strip()
+        if not user_message or user_message.lower() == "exit" or user_message.lower() == "quit":
+            break
+
+        shell_context_assistance(user_message, silent=True, model=model)
+
+    return ActionResult([])

kash/actions/core/chat.py

@@ -0,0 +1,90 @@
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec.preconditions import is_chat
+from kash.form_input.prompt_input import prompt_simple_string
+from kash.llm_utils.chat_format import ChatHistory, ChatMessage, ChatRole
+from kash.llm_utils.language_models import LLMName
+from kash.llm_utils.llm_completion import llm_completion
+from kash.model import (
+    LLM,
+    ONE_OR_NO_ARGS,
+    ActionInput,
+    ActionResult,
+    Format,
+    Item,
+    ItemType,
+    ShellResult,
+    common_params,
+)
+from kash.shell.output.shell_output import (
+    PadStyle,
+    Wrap,
+    print_markdown,
+    print_response,
+    print_style,
+)
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    expected_args=ONE_OR_NO_ARGS,
+    precondition=is_chat,
+    uses_selection=False,
+    interactive_input=True,
+    cacheable=False,
+    params=common_params("model"),
+)
+def chat(input: ActionInput, model: LLMName = LLM.default_careful) -> ActionResult:
+    """
+    Chat with an LLM. By default, starts a new chat session. If provided a chat
+    history item, will continue an existing chat.
+    """
+    if input.items:
+        chat_history = input.items[0].as_chat_history()
+        size_desc = f"{chat_history.size_summary()} in chat history"
+    else:
+        chat_history = ChatHistory()
+        size_desc = "empty chat history"
+
+    print_response(
+        f"Beginning chat with {size_desc}. Press enter (or type `exit`) to end chat.",
+        text_wrap=Wrap.WRAP_FULL,
+    )
+
+    while True:
+        try:
+            user_message = prompt_simple_string(model.litellm_name)
+        except KeyboardInterrupt:
+            break
+
+        user_message = user_message.strip()
+        if not user_message or user_message.lower() == "exit" or user_message.lower() == "quit":
+            break
+
+        chat_history.append(ChatMessage(ChatRole.user, user_message))
+
+        llm_response = llm_completion(
+            model,
+            messages=chat_history.as_chat_completion(),
+        )
+
+        with print_style(PadStyle.PAD):
+            print_markdown(llm_response.content)
+
+        # XXX: Why does the response have trailing whitespace on lines? Makes the YAML ugly.
+        stripped_response = "\n".join(line.rstrip() for line in llm_response.content.splitlines())
+
+        chat_history.append(ChatMessage(ChatRole.assistant, stripped_response))
+
+    if chat_history.messages:
+        item = Item(
+            ItemType.chat,
+            body=chat_history.to_yaml(),
+            format=Format.yaml,
+        )
+
+        return ActionResult([item])
+    else:
+        log.warning("Empty chat! Not saving anything.")
+        return ActionResult([], shell_result=ShellResult(show_selection=False))

kash/actions/core/format_markdown_template.py

@@ -0,0 +1,92 @@
+import re
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.errors import InvalidInput
+from kash.exec import kash_action
+from kash.exec.preconditions import is_markdown
+from kash.model import ONE_OR_MORE_ARGS, ActionInput, ActionResult, ItemType, Param
+from kash.utils.common.type_utils import not_none
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    expected_args=ONE_OR_MORE_ARGS,
+    precondition=is_markdown,
+    params=(
+        Param(
+            "md_template",
+            "Path for the markdown template to use for formatting. This is plain Markdown "
+            "with curly-brace {name} variables for values to insert.",
+            type=Path,
+            default_value=Path("template.md"),
+        ),
+    ),
+)
+def format_markdown_template(
+    input: ActionInput, md_template: Path = Path("template.md")
+) -> ActionResult:
+    """
+    Format the given text documents into a single document using the given
+    template. This is a simple way to generate combined docs from individual
+    pieces or sections, e.g. assembling a readme from a few docs.
+
+    As a convenience, the variables in the template need only be unique
+    matching prefixes of the filename of each item, e.g. {body} for a file
+    named `body.md` or `body_new_01.md`.
+    """
+    template_path = md_template if md_template else Path("template.md")
+    items = input.items
+
+    with open(template_path) as f:
+        template = f.read()
+
+    # Identify variables in the template.
+    variables: list[str] = re.findall(r"\{(\w+)\}", template)
+
+    if len(variables) != len(items):
+        raise InvalidInput(
+            f"Number of inputs ({len(items)} items) does not match the"
+            f" number of variables ({len(variables)}) in the template"
+        )
+
+    # Create a dictionary to map variable names to item bodies.
+    item_map: dict[str, str] = {}
+    unmatched_items = set(range(len(items)))
+
+    for var in variables:
+        matches = []
+        for i, item in enumerate(items):
+            store_path = not_none(item.store_path)
+            filename = Path(store_path).stem
+
+            if not item.body:
+                raise InvalidInput(f"Item has no body: {store_path}")
+
+            if filename.startswith(var):
+                matches.append((i, item))
+
+        if len(matches) == 0:
+            raise InvalidInput(f"No matching item found for variable: `{var}`")
+        elif len(matches) > 1:
+            raise InvalidInput(
+                f"Multiple items match variable `{var}`: {[items[i].store_path for i, _ in matches]}"
+            )
+
+        index, matched_item = matches[0]
+        item_map[var] = matched_item.body
+        unmatched_items.remove(index)
+
+    if unmatched_items:
+        raise InvalidInput(f"Unmatched items: {[items[i].store_path for i in unmatched_items]}")
+
+    # Format the body using the mapped items.
+    body = template.format(**item_map)
+
+    result_item = items[0].derived_copy(
+        type=ItemType.doc,
+        body=body,
+    )
+
+    return ActionResult([result_item])

kash/actions/core/markdownify.py

@@ -0,0 +1,29 @@
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec.preconditions import has_html_body, is_url_item
+from kash.model import Format, Item, ItemType
+from kash.web_content.file_cache_utils import get_url_html
+from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    precondition=is_url_item | has_html_body,
+    mcp_tool=True,
+)
+def markdownify(item: Item) -> Item:
+    """
+    Converts a URL or raw HTML item to Markdown, fetching with the content
+    cache if needed. Also uses readability to clean up the HTML.
+    """
+    from markdownify import markdownify as markdownify_convert
+
+    url, html_content = get_url_html(item)
+    page_data = extract_text_readabilipy(url, html_content)
+    markdown_content = markdownify_convert(page_data.clean_html)
+
+    output_item = item.derived_copy(
+        type=ItemType.doc, format=Format.markdown, body=markdown_content
+    )
+    return output_item

kash/actions/core/readability.py

@@ -0,0 +1,27 @@
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec.preconditions import has_html_body, is_url_item
+from kash.model import Format, Item, ItemType
+from kash.web_content.file_cache_utils import get_url_html
+from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    precondition=is_url_item | has_html_body,
+    mcp_tool=True,
+)
+def readability(item: Item) -> Item:
+    """
+    Extracts clean HTML from a raw HTML item.
+    See `markdownify` to also convert to Markdown.
+    """
+    url, html_content = get_url_html(item)
+    page_data = extract_text_readabilipy(url, html_content)
+
+    output_item = item.derived_copy(
+        type=ItemType.doc, format=Format.html, body=page_data.clean_html
+    )
+
+    return output_item

kash/actions/core/show_webpage.py

@@ -0,0 +1,28 @@
+from kash.actions.core.webpage_config import webpage_config
+from kash.actions.core.webpage_generate import webpage_generate
+from kash.commands.base.show_command import show
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec.preconditions import has_text_body, is_html
+from kash.exec_model.commands_model import Command
+from kash.exec_model.shell_model import ShellResult
+from kash.model import ActionInput, ActionResult
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    precondition=is_html | has_text_body,
+)
+def show_webpage(input: ActionInput) -> ActionResult:
+    """
+    Show text, Markdown, or HTML as a nicely formatted webpage.
+    """
+    config_result = webpage_config(input)
+
+    log.message("Configured web page: %s", config_result)
+    result = webpage_generate(ActionInput(items=config_result.items))
+
+    # Automatically show the result.
+    result.shell_result = ShellResult(display_command=Command.assemble(show))
+    return result

kash/actions/core/strip_html.py

@@ -0,0 +1,28 @@
+from kash.config.logger import get_logger
+from kash.errors import InvalidInput
+from kash.exec import kash_action
+from kash.exec.preconditions import has_html_body, has_text_body
+from kash.model import Format, Item, ItemType
+from kash.utils.common.format_utils import html_to_plaintext
+
+log = get_logger(__name__)
+
+
+@kash_action(precondition=has_html_body | has_text_body)
+def strip_html(item: Item) -> Item:
+    """
+    Strip HTML tags from HTML or Markdown. This is a very dumb filter, simply searching
+    for and removing tags by regex. This works well for clean and simple HTML; use
+    `markdownify` for complex HTML.
+    """
+    if not item.body:
+        raise InvalidInput("Item must have a body")
+
+    clean_body = html_to_plaintext(item.body)
+    output_item = item.derived_copy(
+        type=ItemType.doc,
+        format=Format.markdown,
+        body=clean_body,
+    )
+
+    return output_item

kash/actions/core/summarize_as_bullets.py

@@ -0,0 +1,53 @@
+from kash.exec import kash_action, llm_transform_item
+from kash.llm_utils.language_models import LLMName
+from kash.model import LLM, Item, LLMOptions, Message, MessageTemplate, common_params
+
+llm_options = LLMOptions(
+    system_message=Message(
+        """
+        You are a careful and precise editor.
+        You give exactly the results requested without additional commentary.
+        """
+    ),
+    body_template=MessageTemplate(
+        """
+        Summarize the following text as a list of concise bullet points:
+
+        - Each point should be one sentence long.
+
+        - Format your response as a list of bullet points in Markdown format.
+
+        - Do NOT use nested bullet points. Give a single list, not a list of lists.
+        
+        - Include all key numbers or facts, without omitting any claims or important details.
+        
+        - Use simple and precise language.
+
+        - Simply state the facts or claims without referencing the text or the author. For example, if the
+          text is about cheese being nutritious, you can say "Cheese is nutritious." But do NOT
+          say "The author says cheese is nutritious" or "According to the text, cheese is nutritious."
+
+        - It is very important you do not add any details that are not directly stated in the original text.
+          Do not change any numbers or alter its meaning in any way.
+
+        - Do NOT give any additional response at the beginning, such as "Here are the concise bullet points".
+          Simply give the summary.
+
+        - If the input is very short or so unclear you can't summarize it, simply output "(No results)".
+
+        Input text:
+
+        {body}
+
+        Bullet points:
+        """
+    ),
+)
+
+
+@kash_action(llm_options=llm_options, params=common_params("model"), mcp_tool=True)
+def summarize_as_bullets(item: Item, model: LLMName = LLM.default_basic) -> Item:
+    """
+    Summarize text as bullet points.
+    """
+    return llm_transform_item(item, model=model)

kash/actions/core/webpage_config.py

@@ -0,0 +1,21 @@
+from kash.config.logger import get_logger
+from kash.errors import InvalidInput
+from kash.exec import kash_action
+from kash.model import ActionInput, ActionResult
+from kash.web_gen import tabbed_webpage
+
+log = get_logger(__name__)
+
+
+@kash_action()
+def webpage_config(input: ActionInput) -> ActionResult:
+    """
+    Set up a web page config with optional tabs for each page of content. Uses first item as the page title.
+    """
+    for item in input.items:
+        if not item.body:
+            raise InvalidInput(f"Item must have a body: {item}")
+
+    config_item = tabbed_webpage.webpage_config(input.items)
+
+    return ActionResult([config_item])

kash/actions/core/webpage_generate.py

@@ -0,0 +1,29 @@
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec.preconditions import is_config
+from kash.model import ONE_ARG, ActionInput, ActionResult, FileExt, Format, Item, ItemType
+from kash.web_gen import tabbed_webpage
+
+log = get_logger(__name__)
+
+
+@kash_action(
+    expected_args=ONE_ARG,
+    precondition=is_config,
+)
+def webpage_generate(input: ActionInput) -> ActionResult:
+    """
+    Generate a web page from a configured web page item.
+    """
+    config_item = input.items[0]
+    html = tabbed_webpage.webpage_generate(config_item)
+
+    webpage_item = Item(
+        title=config_item.title,
+        type=ItemType.export,
+        format=Format.html,
+        file_ext=FileExt.html,
+        body=html,
+    )
+
+    return ActionResult([webpage_item])

kash/actions/meta/write_instructions.py

@@ -0,0 +1,39 @@
+from kash.exec import kash_action
+from kash.form_input.prompt_input import prompt_simple_string
+from kash.llm_utils.chat_format import ChatHistory, ChatMessage, ChatRole
+from kash.model import NO_ARGS, ActionInput, ActionResult, Format, Item, ItemType
+
+
+@kash_action(
+    expected_args=NO_ARGS,
+    interactive_input=True,
+    cacheable=False,
+)
+def write_instructions(input: ActionInput) -> ActionResult:
+    """
+    Write a chat item with system and user instructions.
+    """
+    chat_history = ChatHistory()
+
+    system_instructions = prompt_simple_string(
+        "Enter the system instructions (or enter for none): "
+    )
+    system_instructions = system_instructions.strip()
+    if system_instructions:
+        chat_history.append(ChatMessage(ChatRole.system, system_instructions))
+
+    user_instructions = prompt_simple_string("Enter the user instructions: ")
+    user_instructions = user_instructions.strip()
+    if user_instructions:
+        chat_history.append(ChatMessage(ChatRole.user, user_instructions))
+
+    if chat_history.messages:
+        item = Item(
+            type=ItemType.chat,
+            body=chat_history.to_yaml(),
+            format=Format.yaml,
+        )
+
+        return ActionResult([item])
+    else:
+        return ActionResult([])