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

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/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/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/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/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()
 
 

kash/utils/api_utils/api_retries.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+class RetryException(RuntimeError):
+    """
+    Base exception class for retry-related errors.
+    """
+
+
+class RetryExhaustedException(RetryException):
+    """
+    Retries exhausted (this is not retriable).
+    """
+
+    def __init__(self, original_exception: Exception, max_retries: int, total_time: float):
+        self.original_exception = original_exception
+        self.max_retries = max_retries
+        self.total_time = total_time
+
+        super().__init__(
+            f"Max retries ({max_retries}) exhausted after {total_time:.1f}s. "
+            f"Final error: {type(original_exception).__name__}: {original_exception}"
+        )
+
+
+def default_is_retriable(exception: Exception) -> bool:
+    """
+    Default retriable exception checker for common rate limit patterns.
+
+    Args:
+        exception: The exception to check
+
+    Returns:
+        True if the exception should be retried with backoff
+    """
+    # Check for LiteLLM specific exceptions first, as a soft dependency.
+    try:
+        import litellm.exceptions
+
+        # Check for specific LiteLLM exception types
+        if isinstance(
+            exception,
+            (
+                litellm.exceptions.RateLimitError,
+                litellm.exceptions.APIError,
+            ),
+        ):
+            return True
+    except ImportError:
+        # LiteLLM not available, fall back to string-based detection
+        pass
+
+    # Fallback to string-based detection for general patterns
+    exception_str = str(exception).lower()
+    rate_limit_indicators = [
+        "rate limit",
+        "too many requests",
+        "try again later",
+        "429",
+        "quota exceeded",
+        "throttled",
+        "rate_limit_error",
+        "ratelimiterror",
+    ]
+
+    return any(indicator in exception_str for indicator in rate_limit_indicators)
+
+
+@dataclass(frozen=True)
+class RetrySettings:
+    """
+    Retry behavior when handling concurrent requests.
+    """
+
+    max_task_retries: int
+    """Maximum retries per individual task (0 = no retries)"""
+
+    max_total_retries: int | None = None
+    """Maximum retries across all tasks combined (None = no global limit)"""
+
+    initial_backoff: float = 1.0
+    """Base backoff time in seconds"""
+
+    max_backoff: float = 128.0
+    """Maximum backoff time in seconds"""
+
+    backoff_factor: float = 2.0
+    """Exponential backoff multiplier"""
+
+    is_retriable: Callable[[Exception], bool] = default_is_retriable
+    """Function to determine if an exception should be retried"""
+
+
+DEFAULT_RETRIES = RetrySettings(
+    max_task_retries=10,
+    max_total_retries=100,
+    initial_backoff=1.0,
+    max_backoff=128.0,
+    backoff_factor=2.0,
+    is_retriable=default_is_retriable,
+)
+"""Reasonable default retry settings with both per-task and global limits."""
+
+
+NO_RETRIES = RetrySettings(
+    max_task_retries=0,
+    max_total_retries=0,
+    initial_backoff=0.0,
+    max_backoff=0.0,
+    backoff_factor=1.0,
+    is_retriable=lambda _: False,
+)
+"""Disable retries completely."""
+
+
+def extract_retry_after(exception: Exception) -> float | None:
+    """
+    Try to extract retry-after time from exception headers or message.
+
+    Args:
+        exception: The exception to extract retry-after from
+
+    Returns:
+        Retry-after time in seconds, or None if not found
+    """
+    # Check if exception has response headers
+    response = getattr(exception, "response", None)
+    if response:
+        headers = getattr(response, "headers", None)
+        if headers and "retry-after" in headers:
+            try:
+                return float(headers["retry-after"])
+            except (ValueError, TypeError):
+                pass
+
+    # Check for retry_after attribute
+    retry_after = getattr(exception, "retry_after", None)
+    if retry_after is not None:
+        try:
+            return float(retry_after)
+        except (ValueError, TypeError):
+            pass
+
+    return None
+
+
+def calculate_backoff(
+    attempt: int,
+    exception: Exception,
+    *,
+    initial_backoff: float,
+    max_backoff: float,
+    backoff_factor: float,
+) -> float:
+    """
+    Calculate backoff time using exponential backoff with jitter.
+
+    Args:
+        attempt: Current attempt number (0-based)
+        exception: The exception that triggered the backoff
+        initial_backoff: Base backoff time in seconds
+        max_backoff: Maximum backoff time in seconds
+        backoff_factor: Exponential backoff multiplier
+
+    Returns:
+        Backoff time in seconds
+    """
+    # Try to extract retry-after header if available
+    retry_after = extract_retry_after(exception)
+    if retry_after is not None:
+        return min(retry_after, max_backoff)
+
+    # Exponential backoff: initial_backoff * (backoff_factor ^ attempt)
+    exponential_backoff = initial_backoff * (backoff_factor**attempt)
+
+    # Add significant jitter (±50% randomization) to prevent thundering herd
+    jitter_factor = 1 + (random.random() - 0.5) * 1.0
+    backoff_with_jitter = exponential_backoff * jitter_factor
+    # Add a small random base delay (0 to 50% of initial_backoff) to further spread out retries
+    base_delay = random.random() * (initial_backoff * 0.5)
+    total_backoff = backoff_with_jitter + base_delay
+
+    return min(total_backoff, max_backoff)
+
+
+## Tests
+
+
+def test_default_is_retriable():
+    """Test string-based rate limit detection."""
+    # Positive cases
+    assert default_is_retriable(Exception("Rate limit exceeded"))
+    assert default_is_retriable(Exception("Too many requests"))
+    assert default_is_retriable(Exception("HTTP 429 error"))
+    assert default_is_retriable(Exception("Quota exceeded"))
+    assert default_is_retriable(Exception("throttled"))
+    assert default_is_retriable(Exception("RateLimitError"))
+
+    # Negative cases
+    assert not default_is_retriable(Exception("Authentication failed"))
+    assert not default_is_retriable(Exception("Invalid API key"))
+    assert not default_is_retriable(Exception("Network error"))
+
+
+def test_default_is_retriable_litellm():
+    """Test LiteLLM exception detection if available."""
+    try:
+        import litellm.exceptions
+
+        # Test retriable LiteLLM exceptions
+        rate_error = litellm.exceptions.RateLimitError(
+            message="Rate limit", model="test", llm_provider="test"
+        )
+        api_error = litellm.exceptions.APIError(
+            message="API error", model="test", llm_provider="test", status_code=500
+        )
+        assert default_is_retriable(rate_error)
+        assert default_is_retriable(api_error)
+
+        # Test non-retriable exception
+        auth_error = litellm.exceptions.AuthenticationError(
+            message="Auth failed", model="test", llm_provider="test"
+        )
+        assert not default_is_retriable(auth_error)
+
+    except ImportError:
+        # LiteLLM not available, skip
+        pass
+
+
+def test_extract_retry_after():
+    """Test retry-after header extraction."""
+
+    class MockResponse:
+        def __init__(self, headers):
+            self.headers = headers
+
+    class MockException(Exception):
+        def __init__(self, response=None, retry_after=None):
+            self.response = response
+            if retry_after is not None:
+                self.retry_after = retry_after
+            super().__init__()
+
+    # Test response header
+    response = MockResponse({"retry-after": "30"})
+    assert extract_retry_after(MockException(response=response)) == 30.0
+
+    # Test retry_after attribute
+    assert extract_retry_after(MockException(retry_after=45.0)) == 45.0
+
+    # Test no retry info
+    assert extract_retry_after(MockException()) is None
+
+    # Test invalid values
+    invalid_response = MockResponse({"retry-after": "invalid"})
+    assert extract_retry_after(MockException(response=invalid_response)) is None
+
+
+def test_calculate_backoff():
+    """Test backoff calculation."""
+
+    class MockException(Exception):
+        def __init__(self, retry_after=None):
+            self.retry_after = retry_after
+            super().__init__()
+
+    # Test with retry_after header
+    exception = MockException(retry_after=30.0)
+    assert (
+        calculate_backoff(
+            attempt=1,
+            exception=exception,
+            initial_backoff=1.0,
+            max_backoff=60.0,
+            backoff_factor=2.0,
+        )
+        == 30.0
+    )
+
+    # Test exponential backoff with increased jitter and base delay
+    exception = MockException()
+    backoff = calculate_backoff(
+        attempt=1,
+        exception=exception,
+        initial_backoff=1.0,
+        max_backoff=60.0,
+        backoff_factor=2.0,
+    )
+    # base factor * (±50% jitter) + (0-50% of initial_backoff) = range calculation
+    assert 1.0 <= backoff <= 3.5
+
+    # Test max_backoff cap
+    high_backoff = calculate_backoff(
+        attempt=10,
+        exception=exception,
+        initial_backoff=1.0,
+        max_backoff=5.0,
+        backoff_factor=2.0,
+    )
+    assert high_backoff <= 5.0

kash/utils/api_utils/cache_requests_limited.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+from pyrate_limiter import Duration, Limiter, Rate
+from pyrate_limiter.buckets import InMemoryBucket
+from typing_extensions import override
+
+from kash.config.logger import get_logger
+from kash.web_content.file_cache_utils import cache_file
+from kash.web_content.local_file_cache import Loadable
+
+log = get_logger(__name__)
+
+
+class CachingSession(requests.Session):
+    """
+    A `requests.Session` that adds local file caching and optional rate limiting (if
+    `limit` and `limit_interval_secs` are provided). A bit of a hack but enables
+    hot patching libraries that use `requests` without other code changes.
+    """
+
+    def __init__(
+        self,
+        *,
+        limit: int | None = None,
+        limit_interval_secs: int | None = None,
+        max_wait_secs: int = 60 * 5,
+    ):
+        super().__init__()
+        self._limiter: Limiter | None = None
+        if limit and limit_interval_secs:
+            rate = Rate(limit, Duration.SECOND * limit_interval_secs)
+            bucket = InMemoryBucket([rate])
+            # Explicitly set raise_when_fail=False and max_delay to enable blocking.
+            self._limiter = Limiter(
+                bucket, raise_when_fail=False, max_delay=Duration.SECOND * max_wait_secs
+            )
+            log.info(
+                "CachingSession: rate limiting requests with limit=%d, interval=%d, max_wait=%d",
+                limit,
+                limit_interval_secs,
+                max_wait_secs,
+            )
+
+    @override
+    def get(self, url: str | bytes, **kwargs: Any) -> Any:
+        params = kwargs.get("params")
+        # We need a unique key for the cache, so we use the URL and params.
+        url_str = url.decode() if isinstance(url, bytes) else str(url)
+        query_string = urlencode(params or {})
+        url_key = f"{url_str}?{query_string}" if query_string else url_str
+
+        def save(path: Path):
+            if self._limiter:
+                acquired = self._limiter.try_acquire("caching_session_get")
+                if not acquired:
+                    # Generally shouldn't happen.
+                    raise RuntimeError("Rate limiter failed to acquire after maximum delay")
+
+            response = super(CachingSession, self).get(url, **kwargs)
+            response.raise_for_status()
+            content = response.content
+            with open(path, "wb") as f:
+                f.write(content)
+
+        cache_result = cache_file(Loadable(url_key, save))
+
+        if not cache_result.was_cached:
+            log.debug("Cache miss, fetched: %s", url_key)
+        else:
+            log.debug("Cache hit: %s", url_key)
+
+        # A simple hack to make sure response.json() works (e.g. when using wikipediaapi needs).
+        # TODO: Wrap more carefully to ensure other methods work.
+        response = requests.Response()
+        response.status_code = 200
+        response.encoding = "utf-8"
+        response._content = cache_result.content.path.read_bytes()
+        response.url = url_key
+        return response