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

kash/file_storage/item_file_format.py

@@ -22,7 +22,7 @@ _item_cache = MtimeCache[Item](max_size=2000, name="Item")
 
 
 @tally_calls()
-def write_item(item: Item, path: Path):
+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.
@@ -36,7 +36,10 @@ def write_item(item: Item, path: Path):
     # Clear cache before writing.
     _item_cache.delete(path)
 
-    body = normalize_formatting_ansi(item.body_text(), item.format)
+    if normalize:
+        body = normalize_formatting_ansi(item.body_text(), item.format)
+    else:
+        body = item.body_text()
 
     # Special case for YAML files to avoid a possible duplicate `---` divider in the body.
     if body and item.format == Format.yaml:
@@ -48,7 +51,14 @@ def write_item(item: Item, path: Path):
     format = Format(item.format)
     if format == Format.html:
         fm_style = FmStyle.html
-    elif format in [Format.python, Format.kash_script, Format.diff, Format.csv, Format.log]:
+    elif format in [
+        Format.python,
+        Format.shellscript,
+        Format.xonsh,
+        Format.diff,
+        Format.csv,
+        Format.log,
+    ]:
         fm_style = FmStyle.hash
     elif format == Format.json:
         fm_style = FmStyle.slash

kash/file_storage/metadata_dirs.py

@@ -7,7 +7,12 @@ from pathlib import Path
 from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
-from kash.config.settings import CONTENT_CACHE_NAME, DOT_DIR, MEDIA_CACHE_NAME, get_system_cache_dir
+from kash.config.settings import (
+    CONTENT_CACHE_NAME,
+    DOT_DIR,
+    MEDIA_CACHE_NAME,
+    global_settings,
+)
 from kash.file_storage.persisted_yaml import PersistedYaml
 from kash.model.paths_model import StorePath
 from kash.utils.common.format_utils import fmt_loc
@@ -62,7 +67,11 @@ class MetadataDirs:
     # in which case it is in the global cache path.
     @property
     def cache_dir(self) -> Path:
-        return get_system_cache_dir() if self.is_global_ws else StorePath(f"{DOT_DIR}/cache")
+        return (
+            global_settings().system_cache_dir
+            if self.is_global_ws
+            else StorePath(f"{DOT_DIR}/cache")
+        )
 
     @property
     def media_cache_dir(self) -> Path:

kash/help/assistant.py

@@ -110,7 +110,7 @@ def assist_current_state() -> Message:
         ws_info = f"Based on the current directory, the current workspace is: {ws_base_dir.name} at {fmt_loc(ws_base_dir)}"
     else:
         if is_global_ws:
-            about_ws = "You are currently using the `global` workspace."
+            about_ws = "You are currently using the default global workspace."
         else:
             about_ws = "The current directory is not a workspace."
         ws_info = (
@@ -318,7 +318,7 @@ def shell_context_assistance(
                 type=ItemType.script,
                 title=f"Assistant Answer: {capitalize_cms(input)}",
                 description=response_text,
-                format=Format.kash_script,
+                format=Format.shellscript,
                 body=script.script_str,
             )
             ws = current_ws()

kash/help/assistant_instructions.py

@@ -1,10 +1,11 @@
 from functools import cache
 from textwrap import dedent
 
+from strif import StringTemplate
+
 from kash.config.logger import get_logger
 from kash.docs.all_docs import all_docs
 from kash.docs.load_help_topics import load_help_src
-from kash.utils.common.string_template import StringTemplate
 
 log = get_logger(__name__)
 

kash/help/help_embeddings.py

@@ -3,9 +3,9 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from kash.concepts.embeddings import Embeddings
-from kash.concepts.text_similarity import rank_by_relatedness
 from kash.config.logger import get_logger
+from kash.embeddings.embeddings import Embeddings
+from kash.embeddings.text_similarity import rank_by_relatedness
 from kash.help.help_types import HelpDoc, HelpDocType
 from kash.web_content.local_file_cache import Loadable
 

kash/help/help_printing.py

@@ -1,5 +1,8 @@
+from typing import Any
+
 from kash.config.logger import get_logger
 from kash.config.text_styles import STYLE_HINT
+from kash.docs.all_docs import DocSelection
 from kash.exec.action_registry import look_up_action_class
 from kash.exec.command_registry import CommandFunction, look_up_command
 from kash.help.assistant import assist_preamble, assistance_unstructured
@@ -10,7 +13,7 @@ from kash.help.tldr_help import tldr_help
 from kash.llm_utils import LLM
 from kash.llm_utils.llm_messages import Message
 from kash.model.actions_model import Action
-from kash.model.params_model import COMMON_SHELL_PARAMS, RUNTIME_ACTION_PARAMS, Param
+from kash.model.params_model import COMMON_SHELL_PARAMS, Param
 from kash.model.preconditions_model import Precondition
 from kash.shell.output.shell_formatting import format_name_and_description, format_name_and_value
 from kash.shell.output.shell_output import (
@@ -32,7 +35,7 @@ GENERAL_HELP = (
 def _print_command_help(
     name: str,
     description: str | None = None,
-    param_info: list[Param] | None = None,
+    param_info: list[Param[Any]] | None = None,
     precondition: Precondition | None = None,
     verbose: bool = True,
     is_action: bool = False,  # pyright: ignore[reportUnusedParameter]
@@ -91,18 +94,19 @@ def print_command_function_help(command: CommandFunction, verbose: bool = True):
     )
 
 
-def print_action_help(action: Action, verbose: bool = True):
-    params = (
-        list(action.params)
-        + list(RUNTIME_ACTION_PARAMS.values())
-        + list(COMMON_SHELL_PARAMS.values())
-    )
+def print_action_help(
+    action: Action,
+    verbose: bool = True,
+    include_options: bool = True,
+    include_precondition: bool = True,
+):
+    params = action.shell_params if include_options else None
 
     _print_command_help(
         action.name,
         action.description,
         param_info=params,
-        precondition=action.precondition,
+        precondition=action.precondition if include_precondition else None,
         verbose=verbose,
         is_action=True,
         extra_note="(kash action)",
@@ -168,7 +172,7 @@ def print_explain_command(text: str, assistant_model: LLM | None = None):
         # Give the LLM full context on kash APIs.
         # But we do this here lazily to prevent circular dependencies.
         system_message = Message(
-            assist_preamble(is_structured=False, skip_api_docs=False, base_actions_only=False)
+            assist_preamble(is_structured=False, doc_selection=DocSelection.full)
         )
         chat_history.extend(
             [

kash/help/tldr_help.py

@@ -21,7 +21,7 @@ from tldr import (
 )
 
 from kash.config.logger import get_logger
-from kash.docs_base.load_recipe_snippets import RECIPES_DIR
+from kash.docs_base.load_recipe_snippets import RECIPE_EXT, RECIPES_DIR
 from kash.exec_model.commands_model import CommentedCommand
 from kash.exec_model.script_model import BareComment
 from kash.help.help_types import CommandInfo, CommandType
@@ -289,11 +289,13 @@ def dump_all_tldr_snippets(commands: list[str] = RECOMMENDED_TLDR_COMMANDS) -> N
             log.warning("Including command not in a local path: %s", command)
             continue
 
-    with atomic_output_file(RECIPES_DIR / "tldr_standard_commands.ksh") as tmp:
+    with atomic_output_file(RECIPES_DIR / ("tldr_standard_commands" + RECIPE_EXT)) as tmp:
         with open(tmp, "w") as f:
             print("# -- Generated by dump_tldr_snippets --", file=f)
             _write_tldr_snippets(commands, f)
 
     log.message(
-        "Dumped %s TLDR snippets: %s", len(commands), RECIPES_DIR / "tldr_standard_commands.ksh"
+        "Dumped %s TLDR snippets: %s",
+        len(commands),
+        RECIPES_DIR / ("tldr_standard_commands" + RECIPE_EXT),
     )

kash/llm_utils/clean_headings.py

@@ -1,6 +1,6 @@
 from kash.llm_utils import Message, MessageTemplate, llm_template_completion
 from kash.llm_utils.llms import LLM
-from kash.text_handling.markdown_util import as_bullet_points
+from kash.text_handling.markdown_utils import as_bullet_points
 
 # TODO: Enforce that the edits below doesn't contain anything extraneous.
 

kash/llm_utils/llm_api_keys.py

@@ -1,15 +1,15 @@
 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.llm_names import LLMName
 from kash.llm_utils.llms import LLM
-from kash.shell.clideps.api_keys import ApiEnvKey
-from kash.shell.clideps.dotenv_utils import env_var_is_set
 
 
-def api_for_model(model: LLMName) -> ApiEnvKey | None:
+def api_for_model(model: LLMName) -> EnvName | None:
     """
     Get the API key name for a model or None if not found.
     """
@@ -18,7 +18,7 @@ def api_for_model(model: LLMName) -> ApiEnvKey | None:
     except litellm.exceptions.BadRequestError:
         return None
 
-    return ApiEnvKey.for_provider(custom_llm_provider)
+    return EnvName.api_env_name(custom_llm_provider)
 
 
 def have_key_for_model(model: LLMName) -> bool:

kash/llm_utils/llm_completion.py

@@ -6,9 +6,9 @@ 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
-from slugify import slugify
 
 from kash.config.logger import get_logger
 from kash.config.text_styles import EMOJI_TIMING
@@ -113,7 +113,7 @@ def llm_completion(
         chat_history.messages.append(
             ChatMessage(role=ChatRole.assistant, content=content, metadata=metadata)
         )
-        model_slug = slugify(model.litellm_name, separator="_")
+        model_slug = slugify_snake(model.litellm_name)
         log.save_object(
             "LLM response",
             f"llm.{model_slug}",

kash/llm_utils/llm_features.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from prettyfmt import custom_key_sort
+
+from kash.llm_utils.llm_names import LLMName
+from kash.llm_utils.llms import LLM
+
+Speed: TypeAlias = Literal["fast", "medium", "slow"]
+
+ContextSize: TypeAlias = Literal["small", "medium", "large"]
+
+ModelSize: TypeAlias = Literal["small", "medium", "large"]
+
+
+@dataclass(frozen=True)
+class LLMFeatures:
+    speed: Speed | None = None
+    context_size: ContextSize | None = None
+    model_size: ModelSize | None = None
+    structured_output: bool | None = None
+    thinking: bool = False
+
+    def satisfies(self, features: LLMFeatures) -> bool:
+        return all(
+            getattr(self, attr) == getattr(features, attr)
+            for attr in features.__dataclass_fields__
+            if getattr(self, attr) is not None
+        )
+
+
+def pick_llm(desired_features: LLMFeatures) -> LLMName:
+    """
+    Pick the preferred model that satisfies the desired features.
+    """
+    satisfied_models: list[LLMName] = [
+        llm for llm, features in FEATURES.items() if features.satisfies(desired_features)
+    ]
+    satisfied_models.sort(key=custom_key_sort(preferred_llms))
+    if not satisfied_models:
+        raise ValueError(f"No model found for features: {desired_features}")
+    return satisfied_models[0]
+
+
+FEATURES = {
+    LLM.o3_mini: LLMFeatures(
+        speed="fast",
+        context_size="small",
+        model_size="small",
+        structured_output=True,
+        thinking=True,
+    ),
+    # FIXME
+}
+
+preferred_llms: list[LLMName] = [
+    LLM.o3_mini,
+    LLM.o1_mini,
+    LLM.o1,
+    LLM.gpt_4o_mini,
+    LLM.gpt_4o,
+    LLM.gpt_4,
+    LLM.claude_3_7_sonnet,
+    LLM.claude_3_5_sonnet,
+    LLM.claude_3_5_haiku,
+]

kash/llm_utils/llm_messages.py

@@ -10,8 +10,7 @@ from pydantic_core.core_schema import (
     str_schema,
     to_string_ser_schema,
 )
-
-from kash.utils.common.string_template import StringTemplate
+from strif import StringTemplate
 
 
 class Message(str):

kash/llm_utils/llm_names.py

@@ -12,7 +12,7 @@ from pydantic_core.core_schema import (
 )
 from rich.text import Text
 
-from kash.config.text_styles import format_success_emoji
+from kash.shell.output.shell_formatting import format_success_emoji
 from kash.utils.common.type_utils import not_none
 
 

kash/llm_utils/llms.py

@@ -8,18 +8,23 @@ from kash.llm_utils.llm_names import LLMName
 class LLM(LLMName, Enum):
     """
     Convenience names for common LLMs. This isn't exhaustive, but just common
-    ones for autocomplete, docs, etc. Values are all LiteLLM names.
+    ones for autocomplete, docs, etc. Values are all LiteLLM names. See:
+    https://github.com/BerriAI/litellm/blob/main/litellm/model_prices_and_context_window_backup.json
     """
 
     # https://platform.openai.com/docs/models
-    o3_mini = LLMName("o3-mini")
     o1_mini = LLMName("o1-mini")
     o1 = LLMName("o1")
+    o3 = LLMName("o3")
+    o3_mini = LLMName("o3-mini")
+    o4_mini = LLMName("o4-mini")
     o1_preview = LLMName("o1-preview")
     gpt_4o_mini = LLMName("gpt-4o-mini")
     gpt_4o = LLMName("gpt-4o")
     gpt_4 = LLMName("gpt-4")
-    gpt_3_5_turbo = LLMName("gpt-3.5-turbo")
+    gpt_4_1 = LLMName("gpt-4.1")
+    gpt_4_1_mini = LLMName("gpt-4.1-mini")
+    gpt_4_1_nano = LLMName("gpt-4.1-nano")
 
     # https://docs.anthropic.com/en/docs/about-claude/models/all-models
     claude_3_7_sonnet = LLMName("claude-3-7-sonnet-latest")
@@ -35,15 +40,6 @@ class LLM(LLMName, Enum):
     # https://docs.x.ai/docs/models
     xai_grok_2 = LLMName("xai/grok-2-latest")
 
-    # https://docs.mistral.ai/getting-started/models/models_overview/
-    mistral_small = LLMName("mistral/mistral-small-latest")
-    mistral_large = LLMName("mistral/mistral-large-latest")
-    mistral_codestral = LLMName("mistral/mistral-codestral-latest")
-
-    # https://docs.perplexity.ai/guides/model-cards
-    sonar = LLMName("perplexity/sonar")
-    sonar_pro = LLMName("perplexity/sonar-pro")
-
     # https://api-docs.deepseek.com/quick_start/pricing
     deepseek_chat = LLMName("deepseek/deepseek-chat")
     deepseek_coder = LLMName("deepseek/deepseek-coder")
@@ -55,6 +51,15 @@ class LLM(LLMName, Enum):
     groq_deepseek_r1_distill_llama_70b = LLMName("groq/deepseek-r1-distill-llama-70b")
     groq_deepseek_r1_distill_qwen_32b = LLMName("groq/deepseek-r1-distill-qwen-32b")
 
+    # https://docs.perplexity.ai/guides/model-cards
+    sonar = LLMName("perplexity/sonar")
+    sonar_pro = LLMName("perplexity/sonar-pro")
+
+    # https://docs.mistral.ai/getting-started/models/models_overview/
+    mistral_small = LLMName("mistral/mistral-small-latest")
+    mistral_large = LLMName("mistral/mistral-large-latest")
+    mistral_codestral = LLMName("mistral/mistral-codestral-latest")
+
     # Allows use of "default_standard" etc as model names and have the
     # model be looked up from workspace parameter settings.
     default_standard = LLMName("default_standard")

kash/local_server/__init__.py

@@ -1,2 +1,5 @@
-# Ensure commands are registered.
-import kash.local_server.local_server_commands  # noqa: F401
+from pathlib import Path
+
+from kash.exec.importing import import_and_register
+
+import_and_register(__package__, Path(__file__).parent, ["."])

kash/local_server/local_server.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import threading
 from functools import cached_property
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -13,7 +14,10 @@ from prettyfmt import fmt_path
 
 from kash.config.logger import get_logger
 from kash.config.server_config import create_server_config
-from kash.config.settings import atomic_global_settings, global_settings, server_log_file_path
+from kash.config.settings import (
+    atomic_global_settings,
+    global_settings,
+)
 from kash.local_server import local_server_routes
 from kash.local_server.port_tools import find_available_local_port
 from kash.utils.errors import InvalidInput, InvalidState
@@ -31,14 +35,14 @@ def _app_setup() -> FastAPI:
 
     # Map common exceptions to HTTP codes.
     # FileNotFound first, since it might also be an InvalidInput.
-    @app.exception_handler(FileNotFoundError)
+    @app.exception_handler(FileNotFoundError)  # pyright: ignore[reportUntypedFunctionDecorator]
     async def file_not_found_exception_handler(_request: Request, exc: FileNotFoundError):
         return JSONResponse(
             status_code=404,
             content={"message": f"File not found: {exc}"},
         )
 
-    @app.exception_handler(InvalidInput)
+    @app.exception_handler(InvalidInput)  # pyright: ignore[reportUntypedFunctionDecorator]
     async def invalid_input_exception_handler(_request: Request, exc: InvalidInput):
         return JSONResponse(
             status_code=400,
@@ -46,7 +50,7 @@ def _app_setup() -> FastAPI:
         )
 
     # Global exception handler.
-    @app.exception_handler(Exception)
+    @app.exception_handler(Exception)  # pyright: ignore[reportUntypedFunctionDecorator]
     async def global_exception_handler(_request: Request, _exc: Exception):
         return JSONResponse(
             status_code=500,
@@ -56,8 +60,8 @@ def _app_setup() -> FastAPI:
     return app
 
 
-LOCAL_SERVER_NAME = "local_server"
-LOCAL_SERVER_HOST = "127.0.0.1"
+UI_SERVER_NAME = "local_ui_server"
+UI_SERVER_HOST = "127.0.0.1"
 """
 The local hostname to run the local server on.
 
@@ -72,7 +76,7 @@ def _pick_port() -> int:
     """
     settings = global_settings()
     port = find_available_local_port(
-        LOCAL_SERVER_HOST,
+        UI_SERVER_HOST,
         range(
             settings.local_server_ports_start,
             settings.local_server_ports_start + settings.local_server_ports_max,
@@ -86,62 +90,68 @@ def _pick_port() -> int:
 
 
 class LocalServer:
-    def __init__(self):
+    def __init__(self, server_name: str, host: str, log_path: Path):
+        self.server_name = server_name
+        self.host = host
+        self.log_path = log_path
         self.server_lock = threading.RLock()
-        self.server_instance: uvicorn.Server | None = None
         self.did_exit = threading.Event()
+        self.server_instance: uvicorn.Server | None = None
+        self.port: int
 
     @cached_property
     def app(self) -> FastAPI:
         return _app_setup()
 
-    def _run_server(self):
+    @property
+    def host_port(self) -> str | None:
+        if self.server_instance:
+            return f"{self.server_instance.config.host}:{self.server_instance.config.port}"
+        else:
+            return None
+
+    def _setup_server(self):
         import uvicorn
 
         port = _pick_port()
-        self.log_path = server_log_file_path(LOCAL_SERVER_NAME, port)
+        self.port = port
+        config = create_server_config(self.app, self.host, port, self.server_name, self.log_path)
 
-        config = create_server_config(
-            self.app, LOCAL_SERVER_HOST, port, LOCAL_SERVER_NAME, self.log_path
-        )
-        with self.server_lock:
-            server = uvicorn.Server(config)
-            self.server_instance = server
-
-        async def serve():
-            try:
-                log.message(
-                    "Starting local server on %s:%s",
-                    LOCAL_SERVER_HOST,
-                    port,
-                )
-                log.message("Local server logs: %s", fmt_path(server_log_file_path(port)))
-                await server.serve()
-            finally:
-                self.did_exit.set()
+        server = uvicorn.Server(config)
+        self.server_instance = server
 
+    def _run_server_thread(self):
+        assert self.server_instance
         try:
-            asyncio.run(serve())
+            asyncio.run(self.server_instance.serve())
         except Exception as e:
             log.error("Server failed with error: %s", e)
         finally:
-            with self.server_lock:
-                self.server_instance = None
+            self.server_instance = None
+            self.did_exit.set()
 
     def start_server(self):
         with self.server_lock:
             if self.server_instance:
                 log.warning(
-                    "Server already running on %s:%s.",
-                    self.server_instance.config.host,
-                    self.server_instance.config.port,
+                    "Server already running on: %s",
+                    self.host_port,
                 )
                 return
 
             self.did_exit.clear()
-            server_thread = threading.Thread(target=self._run_server, daemon=True)
+
+            self._setup_server()
+
+            server_thread = threading.Thread(target=self._run_server_thread, daemon=True)
             server_thread.start()
             log.info("Created new local server thread: %s", server_thread)
+            log.message(
+                "Started server %s on %s with logs to %s",
+                UI_SERVER_NAME,
+                self.host_port,
+                fmt_path(self.log_path),
+            )
 
     def stop_server(self):
         with self.server_lock:
@@ -159,25 +169,25 @@ class LocalServer:
                     raise InvalidState(f"Server did not shut down within {timeout} seconds")
 
             self.server_instance = None
-            log.warning("Server stopped.")
+            log.warning("Stopped server %s", UI_SERVER_NAME)
 
     def restart_server(self):
         self.stop_server()
         self.start_server()
 
 
-# Singleton instance.
-# Note this is quick to set up (lazy import).
-_local_server = LocalServer()
+# Singleton instance for the UI server.
+# Note this is quick to set up (lazy imports).
+_ui_server = LocalServer(UI_SERVER_NAME, UI_SERVER_HOST, global_settings().local_server_log_path)
 
 
-def start_local_server():
-    _local_server.start_server()
+def start_ui_server():
+    _ui_server.start_server()
 
 
-def stop_local_server():
-    _local_server.stop_server()
+def stop_ui_server():
+    _ui_server.stop_server()
 
 
-def restart_local_server():
-    _local_server.restart_server()
+def restart_ui_server():
+    _ui_server.restart_server()