kash-shell 0.3.20__tar.gz → 0.3.21__tar.gz

{kash_shell-0.3.20 → kash_shell-0.3.21}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier. Do not edit manually.
-_commit: v0.2.13
+_commit: v0.2.14
 _src_path: gh:jlevy/simple-modern-uv
 package_author_email: joshua@cal.berkeley.edu
 package_author_name: Joshua Levy

{kash_shell-0.3.20 → kash_shell-0.3.21}/.cursor/rules/general.mdc

@@ -3,11 +3,14 @@ description: General Guidelines
 globs: 
 alwaysApply: true
 ---
-# General Responses
+# Assistant Rules
 
-Remember you are a senior engineer and have a serious responsibility to be clear,
-factual, think step by step and be systematic, express expert opinion, and make use of
-the user's attention wisely.
+**Your fundamental responsibility:** Remember you are a senior engineer and have a
+serious responsibility to be clear, factual, think step by step and be systematic,
+express expert opinion, and make use of the user's attention wisely.
+
+**Rules must be followed:** It is your responsibility to carefully read these rules as
+well as Python or other language-specific rules included here.
 
 Therefore:
 
@@ -22,8 +25,8 @@ Therefore:
   it. It's your responsibility to suggest approaches that lead to better, simpler
   solutions.
 
-- Give thoughtful opinions on better/worse approaches, but never say "great idea!"
-  or "good job" or other non-essential banter or encouragement.
+- Give thoughtful opinions on better/worse approaches, but NEVER say "great idea!"
+  or "good job" or other compliments, encouragement, or non-essential banter.
   Your job is to give expert opinions and to solve problems, not to motivate the user.
 
 - Avoid gratuitous enthusiasm or generalizations.
@@ -50,18 +53,20 @@ Therefore:
   this is meaningless to anyone reading the code later.
   (Instead, describe in your message to the user any other contextual information.)
 
-- DO NOT use fancy headings like "===== STEP 1: ... =====" in comments
+- DO NOT use fancy or needlessly decorated headings like "===== MIGRATION TOOLS ====="
+  in comments
 
-- DO NOT scatter numbered steps in comments.
+- DO NOT number steps in comments.
   These are hard to maintain if the code changes.
-  Wrong: "// Step 3: Fetch the data from the cache" Correct: "// Now fetch the data from
-  the cache"
-
-## Using Emojis
+  NEVER DO THIS: "// Step 3: Fetch the data from the cache"\
+  This is fine: "// Now fetch the data from the cache"
 
 - DO NOT use emojis or special unicode characters like ① or • or – or — in comments.
 
 - Use emojis in output if it enhances the clarity and can be done consistently.
   You may use ✔︎ and ✘ to indicate success and failure, and ∆ and ‼︎ for user-facing
   warnings and errors, for example, but be sure to do it consistently.
-  But but do not use emojis gratuitously as it clutters the output.
+  DO NOT use emojis gratuitously in comments or output.
+  You may use then ONLY when they have clear meanings (like success or failure).
+  Unless the user says otherwise, avoid emojis and Unicode in comments as clutters the
+  output with little benefit.

{kash_shell-0.3.20 → kash_shell-0.3.21}/.cursor/rules/python.mdc

@@ -90,18 +90,27 @@ Always use full type annotations, generics, and other modern practices.
 - Use strif's `atomic_output_file` context manager when writing files to ensure output
   files are written atomically.
 
-- Use `uv add` and `uv sync` as needed to add dependencies.
+## Use Modern Python Practices
+
+- ALWAYS use `@override` decorators to override methods from base classes.
+  This is a modern Python practice and helps avoid bugs.
 
 ## Testing
 
-- Don't write one-off test code in extra files or within `if __name__ == "__main__":`
-  blocks. Instead, for simple tests, create simple test functions in the original file
-  below a `## Tests` comment.
-  This keeps the tests clear and close to the code.
+- For longer tests put them in a file like `tests/test_somename.py` in the `tests/`
+  directory (or `tests/module_name/test_somename.py` file for a submodule).
+
+- For simple tests, prefer inline functions in the original code file below a `## Tests`
+  comment. This keeps the tests easy to maintain and close to the code.
+  Inline tests should NOT import pytest or pytest fixtures as we do not want runtime
+  dependency on pytest.
 
-- For longer tests `test_somename.py` in the `tests/` directory.
+- DO NOT write one-off test code in extra files that are throwaway.
 
-- Then you can run such tests with `uv run python -s src/.../path/to/test`
+- DO NOT put `if __name__ == "__main__":` just for quick testing.
+  Instead use the inline function tests and run them with `uv run pytest`.
+
+- You can run such individual tests with `uv run pytest -s src/.../path/to/test`
 
 - Don't add docs to assertions unless it's not obvious what they're checking - the
   assertion appears in the stack trace.
@@ -109,16 +118,19 @@ Always use full type annotations, generics, and other modern practices.
   x is 5`. That is redundant.
   Just write `assert x == 5`.
 
+- DO NOT write trivial or obvious tests that are evident directly from code, such as
+  assertions that confirm the value of a constant setting.
+
 - NEVER write `assert False`. If a test reaches an unexpected branch and must fail
   explicitly, `raise AssertionError("Explanation")` instead.
   This is best typical best practice in Python since assertions can be removed with
   optimization.
 
-- Don't use pytest fixtures like parameterized tests or expected exception decorators
+- DO NOT use pytest fixtures like parameterized tests or expected exception decorators
   unless absolutely necessary in more complex tests.
-  It is often far simpler to use simple assertions and put the checks inside the test.
-  This is preferable because then we want simple tests in original source files but
-  don't want pytest dependencies at runtime.
+  It is typically simpler to use simple assertions and put the checks inside the test.
+  This is also preferable because then simple tests have no explicit pytest dependencies
+  and can be placed in code anywhere.
 
 ## Types and Type Annotations
 
@@ -150,7 +162,7 @@ Always use full type annotations, generics, and other modern practices.
     binary = "binary"
   ```
 
-## Guidelines for Formatting Literal strings
+## Guidelines for Literal Strings
 
 - For multi-line strings NEVER put multi-line strings flush against the left margin.
   ALWAYS use a `dedent()` function to make it more readable.
@@ -166,6 +178,22 @@ Always use full type annotations, generics, and other modern practices.
       """).strip()
   ```
 
+## Guidelines for Comments
+
+- Comments should be EXPLANATORY: Explain *WHY* something is done a certain way and not
+  just *what* is done.
+
+- Comments should be CONCISE: Remove all extraneous words.
+
+- DO NOT use comments to state obvious things or repeat what is evident from the code.
+  Here is an example of a comment that SHOULD BE REMOVED because it simply repeats the
+  code, which is distracting and adds no value:
+  ```python
+  if self.failed == 0:
+      # All successful
+      return "All tasks finished successfully"
+  ```
+
 ## Guidelines for Docstrings
 
 - Here is an example of the correct style for docstrings:
@@ -233,3 +261,15 @@ Always use full type annotations, generics, and other modern practices.
         return self.paragraph.reassemble()
   ```
   In general, the user can just call the enclosed objects methods, reducing code bloat.
+
+- If a function does not use a parameter, but it should still be present, you can use `#
+  pyright: ignore[reportUnusedParameter]` in a comment to suppress the linter warning.
+
+## Guidelines for Backward Compatibility
+
+- When changing code in a library or general function, if a change to an API or library
+  will break backward compatibility, MENTION THIS to the user.
+
+- DO NOT implement additional code for backward compatiblity (such as extra methods or
+  variable aliases or comments about backward compatibility) UNLESS the user has
+  confirmed that it is necessary.

{kash_shell-0.3.20 → kash_shell-0.3.21}/.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
       #     python-version: ${{ matrix.python-version }}
 
       - name: Install all dependencies
-        run: uv sync --all-extras --dev
+        run: uv sync --all-extras
 
       - name: Run linting
         run: uv run python devtools/lint.py

{kash_shell-0.3.20 → kash_shell-0.3.21}/.github/workflows/publish.yml

@@ -33,7 +33,7 @@ jobs:
         run: uv python install
 
       - name: Install all dependencies
-        run: uv sync --all-extras --dev
+        run: uv sync --all-extras
 
       - name: Run tests
         run: uv run pytest
@@ -45,3 +45,6 @@ jobs:
 
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always
+        # Although uv is newer and faster, the "official" publishing option is the one from PyPA,
+        # which uses twine. If desired, replace `uv publish` with:
+        # uses: pypa/gh-action-pypi-publish@release/v1

{kash_shell-0.3.20 → kash_shell-0.3.21}/Makefile

@@ -9,7 +9,7 @@
 default: agent-rules install lint test 
 
 install:
-	uv sync --all-extras --dev
+	uv sync --all-extras
 
 lint:
 	uv run python devtools/lint.py

{kash_shell-0.3.20 → kash_shell-0.3.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kash-shell
-Version: 0.3.20
+Version: 0.3.21
 Summary: The knowledge agent shell (core)
 Project-URL: Repository, https://github.com/jlevy/kash-shell
 Author-email: Joshua Levy <joshua@cal.berkeley.edu>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.11
+Requires-Dist: aiolimiter>=1.2.1
 Requires-Dist: anyio>=4.8.0
 Requires-Dist: audioop-lts>=0.2.1; python_version >= '3.13'
 Requires-Dist: cachetools>=5.5.2
@@ -50,6 +51,7 @@ Requires-Dist: pydantic>=2.10.6
 Requires-Dist: pydub>=0.25.1
 Requires-Dist: pygments>=2.19.1
 Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: pyrate-limiter>=3.7.0
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: python-magic-bin>=0.4.14; platform_system == 'Windows'
 Requires-Dist: python-magic>=0.4.27; platform_system == 'Linux' or platform_system == 'Darwin'

{kash_shell-0.3.20 → kash_shell-0.3.21}/development.md

@@ -17,7 +17,7 @@ The `Makefile` simply offers shortcuts to `uv` commands for developer convenienc
 
 ```shell
 # First, install all dependencies and set up your virtual environment.
-# This simply runs `uv sync --all-extras --dev` to install all packages,
+# This simply runs `uv sync --all-extras` to install all packages,
 # including dev dependencies and optional dependencies.
 make install
 

{kash_shell-0.3.20 → kash_shell-0.3.21}/pyproject.toml

@@ -77,10 +77,12 @@ dependencies = [
     "pathspec>=0.12.1",
     "patch-ng>=1.18.1",
     "inquirerpy>=0.3.4",
-    # LLM essentials:
+    # LLM and API essentials:
     "tiktoken>=0.9.0",
     "openai>=1.66.3",
     "litellm>=1.63.11",
+    "pyrate-limiter>=3.7.0",
+    "aiolimiter>=1.2.1",
     # Basic text handling and web scraping:
     "readabilipy>=0.3.0",
     "markdownify>=0.13.1",
@@ -223,6 +225,7 @@ reportMissingParameterType = false
 reportUnannotatedClassAttribute = false
 reportUninitializedInstanceVariable = false
 reportCallInDefaultInitializer = false
+reportUntypedBaseClass = false
 # Make ignoring easier:
 reportIgnoreCommentWithoutRule = false
 reportUnnecessaryTypeIgnoreComment = false

{kash_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/kash/config/text_styles.py

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

{kash_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/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_shell-0.3.20 → kash_shell-0.3.21}/src/kash/shell/output/shell_output.py

@@ -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,20 @@ def console_pager(use_pager: bool = True):
     PrintHooks.after_pager()
 
 
+def multitask_status(
+    settings: StatusSettings | None = None, *, auto_summary: bool = True
+) -> MultiTaskStatus:
+    """
+    Create a `MultiTaskStatus` context manager for displaying multiple task progress
+    using the global shell console.
+    """
+    return MultiTaskStatus(
+        console=get_console(),
+        settings=settings,
+        auto_summary=auto_summary,
+    )
+
+
 null_style = rich.style.Style.null()