kash-shell 0.3.8__py3-none-any.whl → 0.3.10__py3-none-any.whl

kash/config/settings.py

@@ -3,17 +3,18 @@ from enum import Enum
 from functools import cache
 from logging import DEBUG, ERROR, INFO, WARNING
 from pathlib import Path
-from typing import overload
 
 from pydantic.dataclasses import dataclass
+from strif import AtomicVar
 
-from kash.utils.common.atomic_var import AtomicVar
+from kash.config.env_settings import KashEnv
 
 APP_NAME = "kash"
 
 DOT_DIR = ".kash"
 
-GLOBAL_WS_NAME = "global"
+GLOBAL_WS_NAME = "workspace"
+"""Name of the global workspace."""
 
 RECOMMENDED_API_KEYS = [
     "OPENAI_API_KEY",
@@ -23,59 +24,28 @@ RECOMMENDED_API_KEYS = [
 ]
 
 
-@overload
-def path_from_env(env_name: str, default: None) -> None: ...
-
-
-@overload
-def path_from_env(env_name: str, default: Path) -> Path: ...
-
-
-def path_from_env(env_name: str, default: Path | None) -> Path | None:
-    value = os.environ.get(env_name)
-    if value:
-        return Path(value).expanduser().resolve()
-    else:
-        return default.expanduser().resolve() if default else None
-
-
-def get_ws_root_dir() -> Path:
-    """Default root directory for kash workspaces."""
-    return path_from_env("KASH_WS_ROOT", Path("~/Kash").expanduser().resolve())
-
-
-def get_global_ws_dir() -> Path:
-    """Default global workspace directory."""
-    kash_ws_dir = path_from_env("KASH_GLOBAL_WS", None)
-    if kash_ws_dir:
-        return kash_ws_dir
-    else:
-        return get_ws_root_dir() / GLOBAL_WS_NAME
-
-
-def get_system_logs_dir() -> Path:
-    """Default global and system logs directory (for server logs, etc)."""
-    return path_from_env("KASH_SYSTEM_LOGS_DIR", get_ws_root_dir() / "logs")
-
-
-def get_system_cache_dir() -> Path:
-    """Default global and system cache directory (for global media, content, etc)."""
-    return path_from_env("KASH_SYSTEM_CACHE_DIR", get_ws_root_dir() / "cache")
-
-
-def get_mcp_ws_dir() -> Path | None:
+def get_all_common_api_env_vars() -> list[str]:
     """
-    Get the directory for the MCP workspace, if set.
+    Get all the common environment variables that are recommended to be set.
     """
-    mcp_dir = os.environ.get("KASH_MCP_WS")
-    if mcp_dir:
-        return Path(mcp_dir).expanduser().resolve()
-    else:
-        return None
-
-
-def get_rcfile_path() -> Path:
-    return Path("~/.kashrc").expanduser().resolve()
+    from clideps.env_vars.env_names import get_all_common_env_names
+
+    return list(set(get_all_common_env_names() + RECOMMENDED_API_KEYS))
+
+
+RECOMMENDED_PKGS = [
+    "less",
+    "eza",
+    "ripgrep",
+    "bat",
+    "zoxide",
+    "dust",
+    "duf",
+    "pygmentize",
+    "hexyl",
+    "ffmpeg",
+    "imagemagick",
+]
 
 
 MEDIA_CACHE_NAME = "media"
@@ -91,7 +61,7 @@ LOCAL_SERVER_PORT_START = 4470
 LOCAL_SERVER_PORTS_MAX = 30
 
 
-SERVER_LOG_FILE = str(get_system_logs_dir() / "{name}_{port}.log")
+LOCAL_SERVER_LOG_NAME = "local_server"
 
 
 class LogLevel(Enum):
@@ -117,7 +87,7 @@ class LogLevel(Enum):
         return self.name
 
 
-DEFAULT_LOG_LEVEL = LogLevel.parse(os.environ.get("KASH_LOG_LEVEL", "warning"))
+DEFAULT_LOG_LEVEL = LogLevel.parse(KashEnv.KASH_LOG_LEVEL.read_str("warning"))
 
 
 def resolve_and_create_dirs(path: Path | str, is_dir: bool = False) -> Path:
@@ -149,11 +119,15 @@ def find_in_cwd_or_parents(filename: Path | str) -> Path | None:
     return None
 
 
+def _get_rcfile_path() -> Path:
+    return _get_system_config_dir() / "kashrc"
+
+
 def find_rcfiles() -> list[Path]:
     """
     Find active rcfiles. Currently only supports one.
     """
-    rcfile_path = get_rcfile_path()
+    rcfile_path = _get_rcfile_path()
     if rcfile_path.exists():
         return [rcfile_path]
     else:
@@ -162,9 +136,30 @@ def find_rcfiles() -> list[Path]:
 
 @dataclass
 class Settings:
+    ws_root_dir: Path
+    """A default root directory for kash workspaces (typically `~/Kash`)."""
+
+    global_ws_dir: Path
+    """The directory for the default global workspace."""
+
+    system_config_dir: Path
+    """The directory for system-wide configuration files."""
+
     media_cache_dir: Path
     """The workspace media cache directory, for caching audio, video, and transcripts."""
 
+    system_logs_dir: Path
+    """Default global and system logs directory (for server logs, etc)."""
+
+    system_cache_dir: Path
+    """Default global and system cache directory (for global media, content, etc)."""
+
+    mcp_ws_dir: Path | None
+    """The directory for the MCP workspace, if set."""
+
+    local_server_log_path: Path
+    """The path to the local server log."""
+
     content_cache_dir: Path
     """The workspace content cache directory, for caching web or local files."""
     # TODO: Separate workspace cached content (e.g. thumbnails) vs global files
@@ -201,18 +196,60 @@ class Settings:
     """If true, use Nerd Icons in file listings. Requires a compatible font."""
 
 
-@cache
-def server_log_file_path(name: str, port: int | str) -> Path:
-    # Use a different log file for each port (server instance).
-    return resolve_and_create_dirs(SERVER_LOG_FILE.format(name=name, port=port))
+ws_root_dir = Path("~/Kash").expanduser()
 
 
-# Initial default settings.
-_settings = AtomicVar(
-    Settings(
+def _get_ws_root_dir() -> Path:
+    """Default root directory for kash workspaces."""
+    return KashEnv.KASH_WS_ROOT.read_path(default=ws_root_dir)
+
+
+def _get_global_ws_dir() -> Path:
+    kash_ws_dir = KashEnv.KASH_GLOBAL_WS.read_path()
+    if kash_ws_dir:
+        return kash_ws_dir
+    else:
+        return _get_ws_root_dir() / GLOBAL_WS_NAME
+
+
+def get_system_logs_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_LOGS_DIR.read_path(default=_get_ws_root_dir() / "logs")
+
+
+def _get_system_config_dir() -> Path:
+    return Path("~/.config/kash").expanduser().resolve()
+
+
+def _get_system_cache_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_CACHE_DIR.read_path(default=_get_ws_root_dir() / "cache")
+
+
+def _get_mcp_ws_dir() -> Path | None:
+    mcp_dir = KashEnv.KASH_MCP_WS.read_str()
+    if mcp_dir:
+        return Path(mcp_dir).expanduser().resolve()
+    else:
+        return None
+
+
+@cache
+def _get_local_server_log_path() -> Path:
+    return resolve_and_create_dirs(get_system_logs_dir() / f"{LOCAL_SERVER_LOG_NAME}.log")
+
+
+def _read_settings():
+    return Settings(
+        # Essential system settings for logs, workspaces, and configs:
+        ws_root_dir=_get_ws_root_dir(),
+        global_ws_dir=_get_global_ws_dir(),
+        system_config_dir=_get_system_config_dir(),
+        system_logs_dir=get_system_logs_dir(),
+        system_cache_dir=_get_system_cache_dir(),
+        mcp_ws_dir=_get_mcp_ws_dir(),
+        local_server_log_path=_get_local_server_log_path(),
         # These default to the global but can be overridden by workspace settings.
-        media_cache_dir=get_system_cache_dir() / MEDIA_CACHE_NAME,
-        content_cache_dir=get_system_cache_dir() / CONTENT_CACHE_NAME,
+        media_cache_dir=_get_system_cache_dir() / MEDIA_CACHE_NAME,
+        content_cache_dir=_get_system_cache_dir() / CONTENT_CACHE_NAME,
         debug_assistant=True,
         default_editor="nano",
         file_log_level=LogLevel.info,
@@ -224,7 +261,20 @@ _settings = AtomicVar(
         use_kerm_codes=False,
         use_nerd_icons=True,
     )
-)
+
+
+# Initial default settings.
+_settings = AtomicVar(_read_settings())
+
+
+def configure_ws_and_settings(root_dir: Path):
+    """
+    Reset and reload all settings, deriving all paths from the new workspace
+    root. Good if embedding kash in another app.
+    """
+    global ws_root_dir
+    ws_root_dir = root_dir
+    _settings.set(_read_settings())
 
 
 def atomic_global_settings() -> AtomicVar[Settings]:

kash/config/setup.py

@@ -1,25 +1,51 @@
 from enum import Enum
 from functools import cache
+from pathlib import Path
 from typing import Any
 
+from clideps.env_vars.dotenv_utils import load_dotenv_paths
+
+from kash.config.logger import reset_rich_logging
+from kash.config.logger_basic import basic_logging_setup
+from kash.config.settings import LogLevel, configure_ws_and_settings, global_settings
+
 
 @cache
-def setup(rich_logging: bool):
+def kash_setup(
+    *,
+    rich_logging: bool,
+    kash_ws_root: Path | None = None,
+    log_path: Path | None = None,
+    level: LogLevel = LogLevel.info,
+):
     """
-    One-time setup of essential keys, directories, and configs. Idempotent.
+    One-time top-level setup of essential logging, keys, directories, and configs.
+    Idempotent.
+
+    Can call this if embedding kash in another app.
+    Can be used to set the global default workspace and logs directory
+    and/or the default log file.
+    If `rich_logging` is True, then rich logging with warnings only for console use.
+    If `rich_logging` is False, then use basic logging to a file and stderr.
     """
-    from kash.config.logger import reload_rich_logging_setup
-    from kash.shell.clideps.dotenv_utils import load_dotenv_paths
     from kash.utils.common.stack_traces import add_stacktrace_handler
 
-    if rich_logging:
-        reload_rich_logging_setup()
+    add_stacktrace_handler()
 
-    _lib_setup()
+    # Settings may depend on environment variables, so load them first.
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
 
-    add_stacktrace_handler()
+    # Then configure the workspace and settings before finalizing logging.
+    if kash_ws_root:
+        configure_ws_and_settings(kash_ws_root)
 
-    load_dotenv_paths()
+    # Now set up logging, as it might depend on workspace root.
+    if rich_logging:
+        reset_rich_logging(log_path=log_path)
+    else:
+        basic_logging_setup(log_path=log_path, level=level)
+
+    _lib_setup()
 
 
 def _lib_setup():

kash/config/suppress_warnings.py

@@ -1,27 +1,45 @@
 import logging
 import warnings
 from logging import LogRecord
+from typing import Any
+from warnings import formatwarning
+
+FILTER_PATTERNS = [
+    "deprecated",
+    "Deprecation",
+    "PydanticDeprecatedSince20",
+    "pydantic",
+    # "pydub",
+]
+"""Warning messages to always suppress in console output."""
+
+
+def should_suppress(message: Any):
+    return any(pattern in str(message) for pattern in FILTER_PATTERNS)
 
 
 def filter_warnings():
+    for pattern in FILTER_PATTERNS:
+        warnings.filterwarnings("ignore", message=f".*{pattern}.*")
     warnings.filterwarnings("ignore", category=DeprecationWarning)
-    warnings.filterwarnings("ignore", message=".*deprecated.*")
-    warnings.filterwarnings("ignore", message=".*Deprecation.*")
-    warnings.filterwarnings("ignore", message=".*PydanticDeprecatedSince20.*")
-    warnings.filterwarnings("ignore", module="pydub")
-    warnings.filterwarnings("ignore", module="pydantic")
     warnings.filterwarnings("ignore", category=RuntimeWarning, module="xonsh.tools")
 
+    log = logging.getLogger("warnings")
+
+    def custom_showwarning(message, category, filename, lineno, _file=None, line=None):
+        if not should_suppress(message) and not should_suppress(category):
+            log.warning(formatwarning(message, category, filename, lineno, line))
+
+    # Override system default, which writes to stderr.
+    warnings.showwarning = custom_showwarning
+
 
 filter_warnings()
 
 
-# Doing it even more brute force since the approach above often doesn't work.
-def demote_warnings(record: LogRecord):
+# An even more brute force approach if the approach above doesn't work.
+def demote_warnings(record: LogRecord, level: int = logging.INFO):
     if record.levelno == logging.WARNING:
         # Check for any warning patterns that we're filtering in filter_warnings
-        if any(
-            pattern in record.msg
-            for pattern in ["deprecated", "Deprecation", "PydanticDeprecatedSince20"]
-        ) or any(module in str(record.pathname) for module in ["pydub", "pydantic", "xonsh.tools"]):
-            record.levelno = logging.INFO
+        if should_suppress(record.msg) or should_suppress(record.module):
+            record.levelno = level

kash/config/text_styles.py

@@ -46,7 +46,9 @@ SPINNER = "dots12"
 
 BAT_THEME = "Coldark-Dark"
 
-BAT_STYLE = "header-filename,header-filesize,grid,changes"
+BAT_STYLE = "header-filename,header-filesize,grid,numbers,changes"
+
+BAT_STYLE_PLAIN = "plain"
 
 
 ## Colors
@@ -296,18 +298,6 @@ EMOJI_MSG_INDENT = "⋮"
 
 EMOJI_BREADCRUMB_SEP = "›"
 
-EMOJI_TRUE = "✔︎"
-
-EMOJI_FALSE = "✘"
-
-
-def success_emoji(value: bool, success_only: bool = False) -> str:
-    return EMOJI_TRUE if value else " " if success_only else EMOJI_FALSE
-
-
-def format_success_emoji(value: bool, success_only: bool = False) -> Text:
-    return Text(success_emoji(value, success_only), style=COLOR_SUCCESS if value else COLOR_FAILURE)
-
 
 ## Special headings
 

kash/docs/load_api_docs.py

@@ -1,7 +1,8 @@
+from strif import StringTemplate
+
 from kash.config.logger import get_logger
 from kash.docs.load_help_topics import load_help_src
 from kash.docs.load_source_code import load_source_code
-from kash.utils.common.string_template import StringTemplate
 
 log = get_logger(__name__)
 

kash/docs/markdown/topics/a2_installation.md

@@ -65,15 +65,19 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
    For macOS, you can again use brew:
 
    ```shell
-   # Install pyenv, pipx, and other tools:
    brew update
-   brew install ripgrep bat eza hexyl imagemagick libmagic ffmpeg 
+   brew install libmagic ffmpeg ripgrep bat eza hexyl imagemagick zoxide
    ```
 
    For Ubuntu:
 
    ```shell
-   apt install ripgrep bat eza hexyl imagemagick libmagic ffmpeg 
+   sudo apt-get update
+   sudo apt-get install -y libgl1 ffmpeg libmagic-dev 
+   # For the additional command-line tools, pixi is better on Ubuntu:
+   curl -fsSL https://pixi.sh/install.sh | sh
+   . ~/.bashrc
+   pixi global install ripgrep bat eza hexyl imagemagick zoxide
    ```
 
    For Windows or other platforms, see the uv instructions.

kash/docs/markdown/topics/a3_getting_started.md

@@ -243,8 +243,9 @@ A few of the most important commands for managing files and work are these:
   browser to view it.
 
 - `workspace` shows or selects or creates a new workspace.
-  Initially you work in the `global` workspace but for more real work you'll want to
-  create a workspace, which is a directory to hold the files you are working with.
+  Initially you work in the default global workspace (typically at `~/Kash/workspace`)
+  but for more real work you'll want to create a workspace, which is a directory to hold
+  the files you are working with.
 
 - `select` shows or sets selections, which are the set of files the next command will
   run on, within the current workspace.

kash/docs/markdown/warning.md

@@ -1,8 +1,3 @@
-*Thank you for trying kash.
-It is new and has rough edges.
-I'd love to hear from you with issues, bugs, and ideas.
-Discuss at github.com/jlevy/kash and contact info at: github.com/jlevy*
-
-**Warning:** *This is a shell so actions and commands can be destructive or dangerous,
-including deleting files.
-Exercise caution and review commands carefully!*
+**Important:** *Kash will not execute commands without confirmation.
+But this is a shell so commands can be destructive or dangerous.
+Review commands carefully!*

kash/docs/markdown/welcome.md

@@ -5,5 +5,9 @@ You may simply ask a question and the kash assistant will help you.
 Press **space** (or type **?**), then write your question or request.
 Use `logs` for detailed logs.
 
+*I'd love to hear from you with issues, bugs, and ideas.
+Discuss at github.com/jlevy/kash or contact me github.com/jlevy or x.com/ojoshe (DMs
+open).*
+
 Try: `What is kash?`, `How can I transcribe a YouTube video?`, `getting_started`, `faq`,
 `self_check`, `self_configure`

kash/docs_base/load_recipe_snippets.py

@@ -8,7 +8,7 @@ from kash.help.help_types import RecipeScript, RecipeSnippet
 
 log = get_logger(__name__)
 
-RECIPE_EXT = ".ksh"
+RECIPE_EXT = ".sh"
 
 RECIPES_DIR = Path(__file__).parent / "recipes"
 

kash/docs_base/recipes/{general_system_commands.ksh → general_system_commands.sh}

@@ -1,5 +1,5 @@
 
-# Additional snippets not already in tldr_standard_commands.ksh
+# Additional snippets not already in tldr_standard_commands.sh
 
 # Show all current processes running `python`
 procs python

kash/{concepts → embeddings}/cosine.py

@@ -1,9 +1,10 @@
 from collections.abc import Sequence
+from typing import Any, TypeAlias
 
 import numpy as np
 
 # Type aliases for clarity
-ArrayLike = Sequence[float] | np.ndarray
+ArrayLike: TypeAlias = Sequence[float] | np.ndarray[Any, Any]
 
 
 def cosine(u: ArrayLike, v: ArrayLike) -> float:

kash/embeddings/text_similarity.py

@@ -0,0 +1,57 @@
+from typing import cast
+
+import litellm
+from funlog import log_calls
+from litellm import embedding
+from litellm.types.utils import EmbeddingResponse
+
+from kash.config.logger import get_logger
+from kash.embeddings.cosine import ArrayLike, cosine
+from kash.embeddings.embeddings import Embeddings
+from kash.llm_utils.llms import DEFAULT_EMBEDDING_MODEL, EmbeddingModel
+from kash.utils.errors import ApiResultError
+
+log = get_logger(__name__)
+
+
+def cosine_relatedness(x: ArrayLike, y: ArrayLike) -> float:
+    return 1 - cosine(x, y)
+
+
+@log_calls(level="info", show_return_value=False)
+def embed_query(model: EmbeddingModel, query: str) -> EmbeddingResponse:
+    try:
+        response: EmbeddingResponse = cast(
+            EmbeddingResponse, embedding(model=model.litellm_name, input=[query])
+        )
+    except litellm.exceptions.APIError as e:
+        log.info("API error embedding query: %s", e)
+        raise ApiResultError(str(e))
+    if not response.data:
+        log.info("API error embedding query, got: %s", response)
+        raise ApiResultError("No embedding response data")
+    return response
+
+
+@log_calls(level="info", show_return_value=False)
+def rank_by_relatedness(
+    query: str,
+    embeddings: Embeddings,
+    relatedness_fn=cosine_relatedness,
+    model=DEFAULT_EMBEDDING_MODEL,
+    top_n: int = -1,
+) -> list[tuple[str, str, float]]:
+    """
+    Returns a list of strings and relatednesses, sorted from most related to least.
+    """
+    response = embed_query(model, query)
+
+    query_embedding = response.data[0]["embedding"]
+
+    scored_strings = [
+        (key, text, relatedness_fn(query_embedding, emb))
+        for key, text, emb in embeddings.as_iterable()
+    ]
+    scored_strings.sort(key=lambda x: x[2], reverse=True)
+
+    return scored_strings[:top_n]

kash/exec/__init__.py

@@ -1,9 +1,7 @@
-# flake8: noqa: F401
-
 from kash.exec.action_decorators import kash_action, kash_action_class
 from kash.exec.action_exec import SkipItem, prepare_action_input, run_action_with_shell_context
-from kash.exec.action_registry import import_action_subdirs
 from kash.exec.command_registry import kash_command
+from kash.exec.importing import import_and_register
 from kash.exec.llm_transforms import llm_transform_item, llm_transform_str
 from kash.exec.precondition_registry import kash_precondition
 from kash.exec.resolve_args import (
@@ -14,3 +12,22 @@ from kash.exec.resolve_args import (
     resolve_locator_arg,
     resolve_path_arg,
 )
+
+__all__ = [
+    "kash_action",
+    "kash_action_class",
+    "SkipItem",
+    "prepare_action_input",
+    "run_action_with_shell_context",
+    "kash_command",
+    "import_and_register",
+    "llm_transform_item",
+    "llm_transform_str",
+    "kash_precondition",
+    "assemble_path_args",
+    "assemble_store_path_args",
+    "import_locator_args",
+    "resolvable_paths",
+    "resolve_locator_arg",
+    "resolve_path_arg",
+]

kash/exec/action_decorators.py

@@ -210,7 +210,12 @@ def kash_action(
     title_template: TitleTemplate = TitleTemplate("{title}"),
     llm_options: LLMOptions = LLMOptions(),
     override_state: State | None = None,
+    # Including these for completeness but usually don't want to set them globally
+    # in the decorator:
     rerun: bool = False,
+    refetch: bool = False,
+    tmp_output: bool = False,
+    no_format: bool = False,
 ) -> Callable[[AF], AF]:
     """
     A function decorator to create and register an action. The annotated function must
@@ -333,8 +338,11 @@ def kash_action(
                     else:
                         kw_args[fp.name] = self.get_param(fp.name)
 
-                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())
+                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())
+                else:
+                    log.info("Action function has no declared params")
 
                 log.message(
                     "Action function call:\n%s",
@@ -379,11 +387,17 @@ def kash_action(
                 context = provided_context
             else:
                 context = ExecContext(
-                    action, current_ws().base_dir, rerun=rerun, override_state=override_state
+                    action,
+                    current_ws().base_dir,
+                    rerun=rerun,
+                    refetch=refetch,
+                    override_state=override_state,
+                    tmp_output=tmp_output,
+                    no_format=no_format,
                 )
 
             # Run the action.
-            result, _, _ = run_action_with_caching(context, action_input, rerun=rerun)
+            result, _, _ = run_action_with_caching(context, action_input)
 
             return result