kash-shell 0.3.11__py3-none-any.whl → 0.3.12__py3-none-any.whl

kash/exec/runtime_settings.py

@@ -0,0 +1,134 @@
+import contextvars
+from dataclasses import dataclass
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.model.exec_model import RuntimeSettings
+from kash.model.items_model import State
+from kash.workspaces.workspace_dirs import enclosing_ws_dir, global_ws_dir
+
+log = get_logger(__name__)
+
+_current_settings: contextvars.ContextVar[RuntimeSettings | None] = contextvars.ContextVar(
+    "current_runtime_settings", default=None
+)
+"""
+Context variable that tracks the current runtime settings. Only used if it is
+explicitly set with a `with runtime_settings(...):` block.
+"""
+
+
+def current_runtime_settings() -> RuntimeSettings:
+    """
+    Get the current runtime settings. Uses the ambient context var settings if
+    set and otherwise infers the workspace from the current working directory
+    with default runtime settings.
+    """
+
+    ambient_settings = _current_settings.get()
+    if ambient_settings:
+        return ambient_settings
+
+    default_ws_dir = enclosing_ws_dir() or global_ws_dir()
+    return RuntimeSettings(default_ws_dir)
+
+
+@dataclass(frozen=True)
+class WsContext:
+    global_ws_dir: Path
+    enclosing_ws_dir: Path | None
+    override_dir: Path | None
+
+    @property
+    def current_ws_dir(self) -> Path:
+        if self.override_dir:
+            return self.override_dir
+        elif self.enclosing_ws_dir:
+            return self.enclosing_ws_dir
+        else:
+            return self.global_ws_dir
+
+
+def current_ws_context() -> WsContext:
+    """
+    Context path info about the current workspace, including the global workspace
+    directory, any workspace directory that encloses the current working directory,
+    and override set via runtime settings.
+    """
+
+    override_dir = None
+    ambient_settings = _current_settings.get()
+    if ambient_settings:
+        override_dir = ambient_settings.workspace_dir
+
+    return WsContext(global_ws_dir(), enclosing_ws_dir(), override_dir)
+
+
+@dataclass
+class RuntimeSettingsManager:
+    """
+    Manage the context for executing actions, including `RuntimeSettings` and
+    `Workspace`.
+
+    This is a minimal base class for use as a context manager. Most functionality
+    is still in `FileStore`.
+
+    Workspaces may be detected based on the current working directory or explicitly
+    set using a `with` block:
+    ```
+    ws = get_ws("my_workspace")
+    with ws:
+        # code that calls current_ws() will use this workspace
+    ```
+    """
+
+    settings: RuntimeSettings
+
+    def __enter__(self):
+        self._token = _current_settings.set(self.settings)
+        log.info("New runtime context: %s", self.settings)
+        return self.settings
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        _current_settings.reset(self._token)
+        log.info("Exiting runtime context: %s", self.settings)
+
+
+def kash_runtime(
+    workspace_dir: Path | None,
+    *,
+    rerun: bool = False,
+    refetch: bool = False,
+    override_state: State | None = None,
+    tmp_output: bool = False,
+    no_format: bool = False,
+) -> RuntimeSettingsManager:
+    """
+    Set a specific kash execution context for a with block.
+    This allows defining a workspace and other execution settings as the ambient
+    context within the block.
+
+    If `workspace_dir` is not provided, the current workspace will be inferred
+    from the working directory or fall back to the global workspace.
+
+    Example usage:
+    ```
+    with kash_runtime(ws_path, rerun=args.rerun) as runtime:
+        runtime.workspace.log_workspace_info()
+        # Perform actions.
+    ```
+    """
+    from kash.workspaces.workspaces import current_ws
+
+    if workspace_dir is None:
+        workspace_dir = current_ws().base_dir
+
+    settings = RuntimeSettings(
+        workspace_dir=workspace_dir,
+        rerun=rerun,
+        refetch=refetch,
+        override_state=override_state,
+        tmp_output=tmp_output,
+        no_format=no_format,
+    )
+    return RuntimeSettingsManager(settings=settings)

kash/exec/shell_callable_action.py

@@ -13,7 +13,7 @@ from kash.model.params_model import RawParamValues
 from kash.shell.output.shell_output import PrintHooks
 from kash.shell.utils.exception_printing import summarize_traceback
 from kash.utils.common.parse_shell_args import parse_shell_args
-from kash.utils.errors import NONFATAL_EXCEPTIONS
+from kash.utils.errors import get_nonfatal_exceptions
 
 log = get_logger(__name__)
 
@@ -71,14 +71,16 @@ class ShellCallableAction:
                     action_cls, explicit_values, *shell_args.args, rerun=rerun, refetch=refetch
                 )
             # We don't return the result to keep the xonsh shell output clean.
-        except NONFATAL_EXCEPTIONS as e:
+        except get_nonfatal_exceptions() as e:
             PrintHooks.nonfatal_exception()
             log.error(f"[{COLOR_ERROR}]Action error:[/{COLOR_ERROR}] %s", summarize_traceback(e))
             log.info("Action error details: %s", e, exc_info=True)
             return ShellResult(exception=e)
         except Exception as e:
             # Log here while we are in the true call stack (not inside the xonsh call stack).
-            log.error("Action error: %s", e, exc_info=KashEnv.KASH_SHOW_TRACEBACK.read_bool(True))
+            log.error(
+                "Action error: %s", e, exc_info=KashEnv.KASH_SHOW_TRACEBACK.read_bool(default=True)
+            )
             raise
         finally:
             log_tallies(level="warning", if_slower_than=10.0)

kash/file_storage/file_store.py

@@ -5,7 +5,7 @@ import time
 from collections.abc import Callable, Generator
 from os.path import join, relpath
 from pathlib import Path
-from typing import Any, TypeVar
+from typing import Concatenate, ParamSpec, TypeVar
 
 from funlog import format_duration, log_calls
 from prettyfmt import fmt_lines, fmt_path
@@ -13,13 +13,13 @@ from strif import copyfile_atomic, hash_file, move_file
 from typing_extensions import override
 
 from kash.config.logger import get_log_settings, get_logger
-from kash.config.text_styles import EMOJI_SAVED, STYLE_HINT
+from kash.config.text_styles import EMOJI_SAVED
 from kash.file_storage.item_file_format import read_item, write_item
 from kash.file_storage.metadata_dirs import MetadataDirs
 from kash.file_storage.store_filenames import folder_for_type, join_suffix, parse_item_filename
 from kash.model.items_model import Item, ItemId, ItemType
 from kash.model.paths_model import StorePath
-from kash.shell.output.shell_output import PrintHooks, cprint
+from kash.shell.output.shell_output import PrintHooks
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.uniquifier import Uniquifier
 from kash.utils.common.url import Locator, Url, is_url
@@ -34,16 +34,18 @@ from kash.workspaces.workspaces import Workspace
 log = get_logger(__name__)
 
 
+SelfT = TypeVar("SelfT")
 T = TypeVar("T")
+P = ParamSpec("P")
 
 
-def synchronized(method: Callable[..., T]) -> Callable[..., T]:
+def synchronized(method: Callable[Concatenate[SelfT, P], T]) -> Callable[Concatenate[SelfT, P], T]:
     """
     Simple way to synchronize a few methods.
     """
 
     @functools.wraps(method)
-    def synchronized_method(self, *args: Any, **kwargs: Any) -> T:
+    def synchronized_method(self, *args: P.args, **kwargs: P.kwargs) -> T:
         with self._lock:
             return method(self, *args, **kwargs)
 
@@ -316,9 +318,11 @@ class FileStore(Workspace):
         Save the item. Uses the `store_path` if it's already set or generates a new one.
         Updates `item.store_path`.
 
+        Unless `no_format` is true, also normalizes body text formatting (for Markdown)
+        and updates the item's body to match.
+
         If `as_tmp` is true, will save the item to a temporary file.
         If `overwrite` is false, will skip saving if the item already exists.
-        If `no_format` is true, will not normalize body text formatting (for Markdown).
         """
         # If external file already exists within the workspace, the file is already saved (without metadata).
         external_path = item.external_path and Path(item.external_path).resolve()
@@ -475,7 +479,6 @@ class FileStore(Workspace):
                 store_path = self.save(item)
                 log.info("Imported text file: %s", item.as_str())
             else:
-                log.message("Importing non-text file: %s", fmt_loc(path))
                 # Binary or other files we just copy over as-is, preserving the name.
                 # We know the extension is recognized.
                 store_path, _found, old_store_path = self.store_path_for(item)
@@ -586,12 +589,13 @@ class FileStore(Workspace):
         move_file(full_input_path, original_path)
         return StorePath(store_path)
 
-    def log_workspace_info(self, *, once: bool = False):
+    @synchronized
+    def log_workspace_info(self, *, once: bool = False) -> bool:
         """
         Log helpful information about the workspace.
         """
         if once and self.info_logged:
-            return
+            return False
 
         self.info_logged = True
 
@@ -606,25 +610,18 @@ class FileStore(Workspace):
             fmt_path(get_log_settings().log_file_path.absolute(), rel_to_cwd=False),
         )
         log.message(
-            "Media cache: %s", fmt_path(self.base_dir / self.dirs.media_cache_dir, rel_to_cwd=False)
-        )
-        log.message(
-            "Content cache: %s",
+            "Caches: %s, %s",
+            fmt_path(self.base_dir / self.dirs.media_cache_dir, rel_to_cwd=False),
             fmt_path(self.base_dir / self.dirs.content_cache_dir, rel_to_cwd=False),
         )
+        log.message("Current working directory: %s", fmt_path(Path.cwd(), rel_to_cwd=False))
+
         for warning in self.warnings:
             log.warning("%s", warning)
 
-        if self.is_global_ws:
-            PrintHooks.spacer()
-            log.warning("Note you are currently using the default global workspace.")
-            cprint(
-                "Create or switch to another workspace with the `workspace` command.",
-                style=STYLE_HINT,
-            )
-
         log.info("File store startup took %s.", format_duration(self.end_time - self.start_time))
         # TODO: Log more info like number of items by type.
+        return True
 
     def walk_items(
         self,

kash/file_storage/item_file_format.py

@@ -7,7 +7,7 @@ from prettyfmt import custom_key_sort, fmt_size_human
 from kash.config.logger import get_logger
 from kash.model.items_model import ITEM_FIELDS, Item
 from kash.model.operations_model import OPERATION_FIELDS
-from kash.text_handling.doc_normalization import normalize_formatting_ansi
+from kash.text_handling.doc_normalization import normalize_formatting
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.file_utils.file_formats_model import Format
 from kash.utils.file_utils.mtime_cache import MtimeCache
@@ -25,7 +25,7 @@ _item_cache = MtimeCache[Item](max_size=2000, name="Item")
 def write_item(item: Item, path: Path, normalize: bool = True):
     """
     Write a text item to a file with standard frontmatter format YAML.
-    Also normalizes formatting of the body text.
+    By default normalizes formatting of the body text and updates the item's body.
     """
     item.validate()
     if item.is_binary:
@@ -37,7 +37,7 @@ def write_item(item: Item, path: Path, normalize: bool = True):
     _item_cache.delete(path)
 
     if normalize:
-        body = normalize_formatting_ansi(item.body_text(), item.format)
+        body = normalize_formatting(item.body_text(), item.format)
     else:
         body = item.body_text()
 
@@ -79,6 +79,9 @@ def write_item(item: Item, path: Path, normalize: bool = True):
     # Update cache.
     _item_cache.update(path, item)
 
+    # Update the item's body to reflect normalization.
+    item.body = body
+
 
 def read_item(path: Path, base_dir: Path | None) -> Item:
     """

kash/file_storage/store_filenames.py

@@ -1,15 +1,18 @@
+from functools import cache
 from pathlib import Path
 
 from kash.config.logger import get_logger
 from kash.model.items_model import ItemType
+from kash.utils.common.inflection import plural
 from kash.utils.file_utils.file_formats_model import FileExt, Format
 from kash.utils.file_utils.filename_parsing import split_filename
-from kash.utils.lang_utils.inflection import plural
 
 log = get_logger(__name__)
 
 
-_type_to_folder = {name: plural(name) for name, _value in ItemType.__members__.items()}
+@cache
+def _get_type_to_folder() -> dict[str, str]:
+    return {name: plural(name) for name, _value in ItemType.__members__.items()}
 
 
 def folder_for_type(item_type: ItemType) -> Path:
@@ -22,7 +25,7 @@ def folder_for_type(item_type: ItemType) -> Path:
     export -> exports
     etc.
     """
-    return Path(_type_to_folder[item_type.name])
+    return Path(_get_type_to_folder()[item_type.name])
 
 
 def join_suffix(base_slug: str, full_suffix: str) -> str:

kash/llm_utils/init_litellm.py

@@ -0,0 +1,16 @@
+from functools import cache
+
+
+@cache
+def init_litellm():
+    """
+    Configure litellm to suppress overly prominent exception messages.
+    Do this lazily since litellm is slow to import.
+    """
+    try:
+        import litellm
+        from litellm import _logging  # noqa: F401
+
+        litellm.suppress_debug_info = True  # Suppress overly prominent exception messages.
+    except ImportError:
+        pass

kash/llm_utils/llm_api_keys.py

@@ -1,10 +1,9 @@
 from __future__ import annotations
 
-import litellm
 from clideps.env_vars.dotenv_utils import env_var_is_set
 from clideps.env_vars.env_names import EnvName
-from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
 
+from kash.llm_utils.init_litellm import init_litellm
 from kash.llm_utils.llm_names import LLMName
 from kash.llm_utils.llms import LLM
 
@@ -13,6 +12,11 @@ def api_for_model(model: LLMName) -> EnvName | None:
     """
     Get the API key name for a model or None if not found.
     """
+    import litellm
+    from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
+
+    init_litellm()
+
     try:
         _model, custom_llm_provider, _dynamic_api_key, _api_base = get_llm_provider(model)
     except litellm.exceptions.BadRequestError:

kash/llm_utils/llm_completion.py

@@ -1,11 +1,10 @@
+from __future__ import annotations
+
 import time
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
-import litellm
 from flowmark import Wrap, fill_text
 from funlog import format_duration, log_calls
-from litellm.types.utils import Choices, ModelResponse
-from litellm.types.utils import Message as LiteLLMMessage
 from prettyfmt import slugify_snake
 from pydantic import BaseModel
 from pydantic.dataclasses import dataclass
@@ -13,12 +12,16 @@ from pydantic.dataclasses import dataclass
 from kash.config.logger import get_logger
 from kash.config.text_styles import EMOJI_TIMING
 from kash.llm_utils.fuzzy_parsing import is_no_results
+from kash.llm_utils.init_litellm import init_litellm
 from kash.llm_utils.llm_messages import Message, MessageTemplate
 from kash.llm_utils.llm_names import LLMName
 from kash.utils.common.url import Url, is_url
 from kash.utils.errors import ApiResultError
 from kash.utils.file_formats.chat_format import ChatHistory, ChatMessage, ChatRole
 
+if TYPE_CHECKING:
+    from litellm.types.utils import Message as LiteLLMMessage
+
 log = get_logger(__name__)
 
 
@@ -68,6 +71,10 @@ def llm_completion(
     """
     Perform an LLM completion with LiteLLM.
     """
+    import litellm
+    from litellm.types.utils import Choices, ModelResponse
+
+    init_litellm()
 
     chat_history = ChatHistory.from_dicts(messages)
     log.info(

kash/mcp/mcp_cli.py

@@ -9,9 +9,10 @@ import logging
 import os
 from pathlib import Path
 
+from clideps.utils.readable_argparse import ReadableColorFormatter
+
 from kash.config.settings import DEFAULT_MCP_SERVER_PORT, LogLevel, global_settings
 from kash.config.setup import kash_setup
-from kash.shell.utils.argparse_utils import WrappedColorFormatter
 from kash.shell.version import get_version
 
 __version__ = get_version()
@@ -27,7 +28,7 @@ log = logging.getLogger()
 def build_parser():
     from kash.workspaces.workspaces import global_ws_dir
 
-    parser = argparse.ArgumentParser(description=__doc__, formatter_class=WrappedColorFormatter)
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=ReadableColorFormatter)
     parser.add_argument(
         "--version",
         action="version",

kash/mcp/mcp_server_routes.py

@@ -13,12 +13,13 @@ from strif import AtomicVar
 from kash.config.capture_output import CapturedOutput, captured_output
 from kash.config.logger import get_logger
 from kash.config.settings import global_settings
+from kash.exec import kash_runtime
 from kash.exec.action_exec import prepare_action_input, run_action_with_caching
 from kash.exec.action_registry import get_all_actions_defaults, look_up_action_class
-from kash.model.actions_model import Action, ActionResult, ExecContext
+from kash.model.actions_model import Action, ActionResult
+from kash.model.exec_model import ExecContext
 from kash.model.params_model import TypedParamValues
 from kash.model.paths_model import StorePath
-from kash.workspaces.workspaces import current_ws, get_ws
 
 log = get_logger(__name__)
 
@@ -214,9 +215,14 @@ def run_mcp_tool(action_name: str, arguments: dict) -> list[TextContent]:
             # current workspace, which could be changed by the user by changing working
             # directories. Maybe confusing?
             explicit_mcp_ws = global_settings().mcp_ws_dir
-            ws = get_ws(explicit_mcp_ws) if explicit_mcp_ws else current_ws()
 
-            with ws:
+            with kash_runtime(
+                workspace_dir=explicit_mcp_ws,
+                rerun=True,  # Enabling rerun always for now, seems good for tools.
+                refetch=False,  # Using the file caches.
+                # Keeping all transient files for now, but maybe make transient?
+                override_state=None,
+            ) as exec_settings:
                 action_cls = look_up_action_class(action_name)
 
                 # Extract items array and remaining params from arguments.
@@ -228,14 +234,7 @@ def run_mcp_tool(action_name: str, arguments: dict) -> list[TextContent]:
                 action = action_cls.create(param_values)
 
                 # Create execution context and assemble action input.
-                context = ExecContext(
-                    action=action,
-                    workspace_dir=ws.base_dir,
-                    rerun=True,  # Enabling rerun always for now, seems good for tools.
-                    refetch=False,  # Using the file caches.
-                    # Keeping all transient files for now, but maybe make transient?
-                    override_state=None,
-                )
+                context = ExecContext(action=action, settings=exec_settings)
                 action_input = prepare_action_input(*input_items)
 
                 result, result_store_paths, _archived_store_paths = run_action_with_caching(

kash/media_base/transcription_deepgram.py

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
 from os.path import getsize
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from clideps.env_vars.dotenv_utils import load_dotenv_paths
-from deepgram import ListenRESTClient, PrerecordedResponse
 from httpx import Timeout
 
 from kash.config.logger import CustomLogger, get_logger
@@ -10,6 +12,9 @@ from kash.config.settings import global_settings
 from kash.media_base.transcription_format import SpeakerSegment, format_speaker_segments
 from kash.utils.errors import ApiError, ContentError
 
+if TYPE_CHECKING:
+    from deepgram import PrerecordedResponse
+
 log: CustomLogger = get_logger(__name__)
 
 
@@ -19,7 +24,15 @@ def deepgram_transcribe_raw(
     """
     Transcribe an audio file using Deepgram and return the raw response.
     """
-    from deepgram import ClientOptionsFromEnv, DeepgramClient, FileSource, PrerecordedOptions
+    # Slow import, do lazily.
+    from deepgram import (
+        ClientOptionsFromEnv,
+        DeepgramClient,
+        FileSource,
+        ListenRESTClient,
+        PrerecordedOptions,
+        PrerecordedResponse,
+    )
 
     size = getsize(audio_file_path)
     log.info(

kash/model/__init__.py

@@ -20,7 +20,6 @@ from kash.model.actions_model import (
     Action,
     ActionInput,
     ActionResult,
-    ExecContext,
     LLMOptions,
     PathOp,
     PathOpType,
@@ -33,6 +32,7 @@ from kash.model.compound_actions_model import (
     look_up_actions,
 )
 from kash.model.concept_model import Concept, canonicalize_concept, normalize_concepts
+from kash.model.exec_model import ExecContext
 from kash.model.graph_model import GraphData, Link, Node
 from kash.model.items_model import (
     SLUG_MAX_LEN,

kash/model/actions_model.py

@@ -4,7 +4,6 @@ from abc import ABC, abstractmethod
 from dataclasses import Field as DataclassField
 from dataclasses import field, replace
 from enum import Enum
-from pathlib import Path
 from textwrap import dedent
 from typing import Any, TypeVar, cast
 
@@ -20,10 +19,10 @@ from typing_extensions import override
 from kash.config.logger import get_logger
 from kash.exec_model.args_model import NO_ARGS, ONE_ARG, ArgCount, ArgType, Signature
 from kash.exec_model.shell_model import ShellResult
-from kash.file_storage.file_store import FileStore
 from kash.llm_utils import LLM, LLMName
 from kash.llm_utils.llm_messages import Message, MessageTemplate
-from kash.model.items_model import UNTITLED, Item, ItemType, State
+from kash.model.exec_model import ExecContext
+from kash.model.items_model import UNTITLED, Item, ItemType
 from kash.model.operations_model import Operation, Source
 from kash.model.params_model import (
     ALL_COMMON_PARAMS,
@@ -38,7 +37,6 @@ from kash.model.preconditions_model import Precondition
 from kash.utils.common.parse_key_vals import format_key_value
 from kash.utils.common.type_utils import not_none
 from kash.utils.errors import InvalidDefinition, InvalidInput
-from kash.workspaces.workspaces import get_ws
 
 log = get_logger(__name__)
 
@@ -64,53 +62,6 @@ class ActionInput:
         return ActionInput(items=[])
 
 
-@dataclass(frozen=True)
-class ExecContext:
-    """
-    An action and its context for execution. This is a good place for settings
-    that apply to any action and are bothersome to pass as parameters.
-    """
-
-    action: Action
-    """The action being executed."""
-
-    workspace_dir: Path
-    """The workspace directory in which the action is being executed."""
-
-    rerun: bool = False
-    """If True, always run actions, even cacheable ones that have results."""
-
-    refetch: bool = False
-    """If True, will refetch items even if they are already in the content caches."""
-
-    override_state: State | None = None
-    """If specified, override the state of result items. Useful to mark items as transient."""
-
-    tmp_output: bool = False
-    """If True, will save output items to a temporary file."""
-
-    no_format: bool = False
-    """If True, will not normalize the output item's body text formatting (for Markdown)."""
-
-    @property
-    def workspace(self) -> FileStore:
-        return get_ws(self.workspace_dir)
-
-    @property
-    def runtime_options(self) -> dict[str, str]:
-        """Return non-default runtime options."""
-        opts: dict[str, str] = {}
-        # Only these two settings directly affect the output:
-        if self.no_format:
-            opts["no_format"] = "true"
-        if self.override_state:
-            opts["override_state"] = self.override_state.name
-        return opts
-
-    def __repr__(self):
-        return abbrev_obj(self, field_max_len=80)
-
-
 class PathOpType(Enum):
     archive = "archive"
     select = "select"
@@ -365,8 +316,8 @@ class Action(ABC):
         """
         Declaration sanity checks.
         """
-        if not self.name or not self.description:
-            raise InvalidDefinition("Action must have a name and description")
+        if not self.name:
+            raise InvalidDefinition("Action must have a name")
 
         for param in self.params:
             if not self.has_param(param.name):
@@ -535,7 +486,7 @@ class Action(ABC):
                 log.info("Ignoring parameter for action `%s`: `%s`", self.name, param_name)
 
         if overrides:
-            log.message(
+            log.info(
                 "Overriding parameters for action `%s`:\n%s",
                 self.name,
                 fmt_lines(overrides),
@@ -677,3 +628,4 @@ class PerItemAction(Action, ABC):
 
 # Handle circular dependency in Python dataclasses.
 rebuild_dataclass(Item)  # pyright: ignore
+rebuild_dataclass(ExecContext)  # pyright: ignore