kash-shell 0.3.28__py3-none-any.whl → 0.3.33__py3-none-any.whl

kash/model/compound_actions_model.py

@@ -5,7 +5,8 @@ from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.exec.combiners import Combiner
-from kash.model.actions_model import Action, ActionInput, ActionResult, ExecContext
+from kash.model.actions_model import Action, ActionInput, ActionResult
+from kash.model.exec_model import ActionContext
 from kash.model.items_model import Item, State
 from kash.model.params_model import RawParamValues
 from kash.model.paths_model import StorePath
@@ -46,7 +47,7 @@ class SequenceAction(Action):
         )
         self.description = seq_description
 
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         from kash.exec.action_exec import run_action_with_shell_context
         from kash.workspaces import current_ws
 
@@ -140,7 +141,7 @@ class ComboAction(Action):
 
         self.description = combo_description
 
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         from kash.exec.action_exec import run_action_with_shell_context
         from kash.exec.combiners import combine_as_paragraphs
 

kash/model/exec_model.py

@@ -8,10 +8,11 @@ from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.model.items_model import State
+from kash.model.operations_model import Operation
 
 if TYPE_CHECKING:
     from kash.file_storage.file_store import FileStore
-    from kash.model.actions_model import Action
+    from kash.model.actions_model import Action, ActionInput
 
 
 log = get_logger(__name__)
@@ -42,6 +43,9 @@ class RuntimeSettings:
     no_format: bool = False
     """If True, will not normalize the output item's body text formatting (for Markdown)."""
 
+    sync_to_s3: bool = True
+    """If True, will sync output items to S3 if input was from S3."""
+
     @property
     def workspace(self) -> FileStore:
         from kash.workspaces.workspaces import get_ws
@@ -68,8 +72,8 @@ class RuntimeSettings:
 @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.
+    An action and its general context for execution. This is a good place for general
+    settings that apply to any action and are bothersome to pass as parameters.
     """
 
     action: Action
@@ -77,3 +81,29 @@ class ExecContext:
 
     settings: RuntimeSettings
     """The workspace and other run-time settings for the action."""
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    """
+    All context for the currently executing action, with all inputs and options.
+    """
+
+    exec_context: ExecContext
+    """The context of the current execution."""
+
+    action_input: ActionInput
+    """The assembled input to the current action."""
+
+    operation: Operation
+    """The operation in full detail, including inputs and options."""
+
+    @property
+    def action(self) -> Action:
+        """The action being executed."""
+        return self.exec_context.action
+
+    @property
+    def settings(self) -> RuntimeSettings:
+        """The workspace and other run-time settings for the action."""
+        return self.exec_context.settings

kash/model/items_model.py

@@ -17,7 +17,7 @@ from prettyfmt import (
     slugify_snake,
 )
 from pydantic.dataclasses import dataclass
-from strif import abbrev_str, format_iso_timestamp
+from strif import abbrev_str, format_iso_timestamp, single_line
 
 from kash.config.logger import get_logger
 from kash.model.concept_model import canonicalize_concept
@@ -34,7 +34,9 @@ from kash.utils.text_handling.markdown_render import markdown_to_html
 from kash.utils.text_handling.markdown_utils import first_heading
 
 if TYPE_CHECKING:
-    from kash.model.exec_model import ExecContext
+    from sidematter_format import ResolvedSidematter
+
+    from kash.model.exec_model import ActionContext
     from kash.workspaces import Workspace
 
 log = get_logger(__name__)
@@ -68,7 +70,15 @@ class ItemType(Enum):
         """
         Resources don't have a body. On concepts it's optional.
         """
-        return self.value not in [ItemType.resource.value, ItemType.concept.value]
+        return self.value not in (ItemType.resource.value, ItemType.concept.value)
+
+    @property
+    def allows_op_suffix(self) -> bool:
+        """
+        Whether it makes sense to have an operation suffix for this item type
+        (docs often should, but concepts or resources can have cleaner naming conventions).
+        """
+        return self not in (ItemType.concept, ItemType.resource, ItemType.export)
 
     @staticmethod
     def for_format(format: Format) -> ItemType:
@@ -100,6 +110,7 @@ class ItemType(Enum):
             Format.mp3: ItemType.resource,
             Format.m4a: ItemType.resource,
             Format.mp4: ItemType.resource,
+            Format.zip: ItemType.resource,
         }
         return format_to_item_type.get(format, ItemType.resource)
 
@@ -192,6 +203,15 @@ class ItemId:
             # If we got here, the item has no identity.
             item_id = None
 
+        log.debug(
+            "item_id is %s for type=%s, format=%s, url=%s, title=%s, source=%s",
+            item_id,
+            item.type,
+            item.format,
+            item.url,
+            item.title,
+            item.source,
+        )
         return item_id
 
 
@@ -267,7 +287,7 @@ class Item:
 
     # Optional execution context. Useful for letting functions that take only an Item
     # arg get access to context.
-    context: ExecContext | None = field(default=None, metadata={"exclude": True})
+    context: ActionContext | None = field(default=None, metadata={"exclude": True})
 
     # These fields we don't want in YAML frontmatter.
     # We don't include store_path as it's redundant with the filename.
@@ -369,9 +389,9 @@ class Item:
         item_type: ItemType | None = None,
         *,
         title: str | None = None,
-        original_filename: str | None = None,
         url: Url | None = None,
         mime_type: MimeType | None = None,
+        preserve_filename: bool = True,
     ) -> Item:
         """
         Create a resource Item for a file with a format inferred from the file extension
@@ -400,9 +420,10 @@ class Item:
         if not file_ext:
             file_ext = format_info.suggested_file_ext
 
+        original_filename = Path(path).name if preserve_filename else None
         item = cls(
             type=item_type,
-            title=title,
+            title=single_line(title) if title else None,  # Avoid multiline titles.
             file_ext=file_ext,
             format=format,
             external_path=str(path),
@@ -428,7 +449,7 @@ class Item:
         return cls(
             type=ItemType.resource,
             format=Format.url,
-            title=media_metadata.title,
+            title=single_line(media_metadata.title),  # Avoid multiline titles.
             url=media_metadata.url,
             description=media_metadata.description,
             thumbnail_url=media_metadata.thumbnail_url,
@@ -453,7 +474,7 @@ class Item:
         if self.type.expects_body and self.format.has_body and not self.body:
             raise ValueError(f"Item type `{self.type.value}` is text but has no body: {self}")
 
-    def absolute_path(self, ws: Workspace | None = None) -> Path:
+    def absolute_path(self, ws: Path | Workspace | None = None) -> Path:
         """
         Get the absolute path to the item. Throws `ValueError` if the item has no
         store path. If no workspace is provided, uses the current workspace.
@@ -462,8 +483,11 @@ class Item:
 
         if not self.store_path:
             raise ValueError("Item has no store path")
-        if not ws:
+        elif isinstance(ws, Path):
+            return ws / self.store_path
+        elif not ws:
             ws = current_ws()
+
         return ws.base_dir / self.store_path
 
     @property
@@ -485,7 +509,7 @@ class Item:
             raise ValueError("Cannot get doc id for an item that has not been saved")
         return str(self.store_path)
 
-    def metadata(self, datetime_as_str: bool = False) -> dict[str, Any]:
+    def metadata(self, *, datetime_as_str: bool = False) -> dict[str, Any]:
         """
         Metadata is all relevant non-None fields in easy-to-serialize form.
         Optional fields are omitted unless they are set.
@@ -529,6 +553,15 @@ class Item:
 
         return item_dict
 
+    def sidematter(self, ws: Path | Workspace | None = None) -> ResolvedSidematter:
+        """
+        Get the sidematter for this item, if present, by looking at the files
+        in the specified workspace (or the current workspace if not specified).
+        """
+        from sidematter_format import Sidematter
+
+        return Sidematter(self.absolute_path(ws)).resolve()
+
     def filename_stem(self) -> str | None:
         """
         If the item has an existing or previous filename, return its stem,
@@ -545,16 +578,25 @@ class Item:
             path_name = None
         return path_name
 
-    def slug_name(self, max_len: int = SLUG_MAX_LEN, prefer_title: bool = False) -> str:
+    def slug_name(
+        self,
+        max_len: int = SLUG_MAX_LEN,
+        prefer_title: bool = False,
+        add_ops_suffix: bool = True,
+    ) -> str:
         """
         Get a readable slugified name for this item, either from a previous filename
-        or from slugifying the title or content. May not be unique.
+        or from slugifying the title or content. Adds the last operation suffix if requested
+        and available in item history.
         """
-        filename_stem = self.filename_stem()
-        if filename_stem and not prefer_title:
-            return slugify_snake(filename_stem)
+        base_title = self.filename_stem()
+        if prefer_title or not base_title:
+            base_title = self.pick_title(max_len=max_len, add_ops_suffix=add_ops_suffix)
         else:
-            return slugify_snake(self.pick_title(max_len=max_len, add_ops_suffix=True))
+            base_title = self.pick_title(
+                base_title=base_title, max_len=max_len, add_ops_suffix=add_ops_suffix
+            )
+        return slugify_snake(base_title)
 
     def default_filename(self) -> str:
         """
@@ -578,6 +620,7 @@ class Item:
 
     def pick_title(
         self,
+        base_title: str | None = None,
         *,
         max_len: int = 100,
         add_ops_suffix: bool = False,
@@ -590,35 +633,31 @@ class Item:
         """
         # First special case: if we are pulling the title from the body header, check
         # that.
-        if not self.title and pull_body_heading:
-            heading = self.body_heading()
-            if heading:
-                return heading
-
-        # Next special case: URLs with no title use the url itself.
-        if not self.title and self.url:
-            return abbrev_str(self.url, max_len)
-
-        filename_stem = self.filename_stem()
-
-        # Use the title or the path if possible, falling back to description or even body text.
-        title_raw_text = (
-            self.title
-            or filename_stem
-            or self.description
-            or (not self.is_binary and self.abbrev_body(max_len))
-            or UNTITLED
-        )
+        if not base_title:
+            if not base_title and pull_body_heading:
+                heading = self.body_heading()
+                base_title = heading
+
+            # Next special case: URLs with no title use the url itself.
+            if not self.title and self.url:
+                return abbrev_str(self.url, max_len)
+
+            filename_stem = self.filename_stem()
+
+            # Use the title or the path if possible, falling back to description or even body text.
+            base_title = (
+                self.title
+                or filename_stem
+                or self.description
+                or (not self.is_binary and self.abbrev_body(max_len))
+                or UNTITLED
+            )
 
-        suffix = ""
         # For docs, etc but not for concepts/resources/exports, add a parenthical note
         # indicating the last operation, if there was one. This makes filename slugs
         # more readable.
-        if add_ops_suffix and self.type not in [
-            ItemType.concept,
-            ItemType.resource,
-            ItemType.export,
-        ]:
+        suffix = ""
+        if add_ops_suffix and self.type.allows_op_suffix:
             last_op = self.history and self.history[-1].action_name
             if last_op:
                 step_num = len(self.history) + 1 if self.history else 1
@@ -626,7 +665,7 @@ class Item:
 
         shorter_len = min(max_len, max(max_len - len(suffix), 20))
         clean_text = sanitize_title(
-            abbrev_phrase_in_middle(html_to_plaintext(title_raw_text), shorter_len)
+            abbrev_phrase_in_middle(html_to_plaintext(base_title), shorter_len)
         )
 
         final_text = clean_text
@@ -670,8 +709,6 @@ class Item:
         """
         If it is a data Item, return the parsed YAML.
         """
-        if not self.type == ItemType.data:
-            raise FileFormatError(f"Item is not a data item: {self}")
         if not self.body:
             raise FileFormatError(f"Data item has no body: {self}")
         if self.format != Format.yaml:
@@ -795,15 +832,24 @@ class Item:
         merged_fields = self._copy_and_update(other, update_timestamp=False)
         return Item(**merged_fields)
 
-    def derived_copy(self, **updates: Unpack[ItemUpdateOptions]) -> Item:
+    def derived_copy(
+        self,
+        action_context: ActionContext | None = None,
+        output_num: int = 0,
+        **updates: Unpack[ItemUpdateOptions],
+    ) -> Item:
         """
         Copy item with the given field updates. Resets `store_path` and `source` to None
         since those should be set explicitly later. Preserves other fields, including
-        the body.
+        the type and the body.
 
         Same as `new_copy_with` but also updates the `derived_from` relation. If we also
-        have an action context, then use the `title_template` to derive a new title.
+        have an action context, then use that to fill some fields, in particular `title_template`
+        to derive a new title and `output_type` and `output_format` to set the output type
+        and format
         """
+
+        # Get derived_from relation if possible.
         if not self.store_path:
             if self.relations.derived_from:
                 log.message(
@@ -830,30 +876,58 @@ class Item:
             assert updates["format"] is not None
             updates["file_ext"] = updates["format"].file_ext
 
-        # External resource paths only make sense for resources, so clear them out if new item
-        # is not a resource.
-        new_type = updates.get("type") or self.type
-        if "external_path" not in updates and new_type != ItemType.resource:
+        # External resource paths should not be preserved.
+        if "external_path" not in updates:
             updates["external_path"] = None
 
+        action_context = action_context or self.context
+
+        if action_context:
+            # Default the output item type and format to the action's declared output_type
+            # and format if not explicitly set.
+            if "type" not in updates:
+                updates["type"] = action_context.action.output_type
+            # If we were not given a format override, we leave the output type the same.
+            elif action_context.action.output_format:
+                # Check an overridden format and then our own format.
+                new_output_format = updates.get("format", self.format)
+                if new_output_format and action_context.action.output_format != new_output_format:
+                    log.warning(
+                        "Output item format `%s` does not match declared output format `%s` for action `%s`",
+                        new_output_format,
+                        action_context.action.output_format,
+                        action_context.action.name,
+                    )
+
         new_item = self.new_copy_with(update_timestamp=True, **updates)
         if derived_from:
             new_item.update_relations(derived_from=derived_from)
 
+        # Record the history.
+        if action_context:
+            new_item.update_source(
+                Source(
+                    operation=action_context.operation,
+                    output_num=output_num,
+                    cacheable=action_context.action.cacheable,
+                )
+            )
+            action = action_context.action
+        else:
+            action = None
+
         # Fall back to action title template if we have it and title wasn't explicitly set.
         if "title" not in updates:
             prev_title = self.title or (Path(self.store_path).stem if self.store_path else UNTITLED)
-            if self.context:
-                action = self.context.action
-                new_item.title = action.title_template.format(
-                    title=prev_title, action_name=action.name
-                )
+
+            if action:
+                new_item.title = action.format_title(prev_title)
             else:
-                log.warning(
+                log.info(
                     "Deriving an item without action context so keeping previous title: %s",
                     self,
                 )
-                new_item.title = f"{prev_title} (derived copy)"
+                new_item.title = prev_title
 
         return new_item
 
@@ -866,9 +940,10 @@ class Item:
             setattr(self.relations, key, list(value))
         return self.relations
 
-    def update_history(self, source: Source) -> None:
+    def update_source(self, source: Source) -> None:
         """
-        Update the history of the item with the given operation.
+        Update the source and the history of the item to indicate it was created
+        by the given operation. For convenience, this is idempotent.
         """
         self.source = source
         self.add_to_history(source.operation.summary())
@@ -900,12 +975,26 @@ class Item:
         return metadata_matches and body_matches
 
     def add_to_history(self, operation_summary: OperationSummary):
+        """
+        For convenience, this is idempotent.
+        """
         if not self.history:
             self.history = []
         # Don't add duplicates to the history.
         if not self.history or self.history[-1] != operation_summary:
             self.history.append(operation_summary)
 
+    def mark_as_saved(self, external_path: Path) -> None:
+        """
+        Mark the item as saved at an external or internal path. If this item is saved to a
+        workspace and the path is inside the workspace, the save will be short-circuited.
+        If it's outside the workspace, the item will be copied to the workspace.
+        Having this method makes it quick to catch bugs where the file is missing.
+        """
+        if not external_path.exists():
+            raise FileNotFoundError(f"Provided path not found: {fmt_loc(external_path)}")
+        self.external_path = str(external_path)
+
     def fmt_loc(self) -> str:
         """
         Formatted store path, external path, URL, or title. Use for logging etc.
@@ -949,6 +1038,7 @@ class Item:
                 key_filter={
                     "store_path": 0,
                     "external_path": 64,
+                    "original_filename": 64,
                     "type": 64,
                     "format": 64,
                     "state": 64,

kash/model/params_model.py

@@ -206,10 +206,10 @@ A list of parameter declarations, possibly with default values.
 
 # These are the default models for typical use cases.
 # The user may override them with parameters.
-DEFAULT_CAREFUL_LLM = LLM.o3
-DEFAULT_STRUCTURED_LLM = LLM.gpt_4o
-DEFAULT_STANDARD_LLM = LLM.claude_4_sonnet
-DEFAULT_FAST_LLM = LLM.gpt_4o
+DEFAULT_CAREFUL_LLM = LLM.gpt_5
+DEFAULT_STRUCTURED_LLM = LLM.gpt_5
+DEFAULT_STANDARD_LLM = LLM.gpt_5
+DEFAULT_FAST_LLM = LLM.gpt_5_mini
 
 
 # Parameters set globally such as in the workspace.

kash/shell/output/shell_output.py

@@ -10,7 +10,6 @@ from enum import Enum, auto
 import rich
 import rich.style
 from flowmark import Wrap, fill_text
-from flowmark.text_filling import DEFAULT_INDENT
 from rich.console import Group, OverflowMethod, RenderableType
 from rich.rule import Rule
 from rich.style import Style
@@ -50,7 +49,7 @@ def print_style(pad_style: PadStyle):
     Context manager for print styles.
     """
     if pad_style == PadStyle.INDENT:
-        token = print_context_var.set(DEFAULT_INDENT)
+        token = print_context_var.set("    ")
         try:
             yield
         finally:

kash/utils/api_utils/gather_limited.py

@@ -542,6 +542,8 @@ async def gather_limited_sync(
             # Mark as failed
             if status and task_id is not None:
                 await status.finish(task_id, TaskState.FAILED, str(e))
+
+            log.warning("Task failed: %s: %s", label, e, exc_info=True)
             raise
 
     return await _gather_with_interrupt_handling(

kash/utils/api_utils/multitask_gather.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, TypeVar
+
+from kash.config.logger import get_logger
+from kash.config.settings import global_settings
+from kash.shell.output.shell_output import multitask_status
+from kash.utils.api_utils.api_retries import RetrySettings
+from kash.utils.api_utils.gather_limited import FuncTask, Limit, gather_limited_sync
+
+T = TypeVar("T")
+
+log = get_logger(name=__name__)
+
+
+def _default_labeler(total: int) -> Callable[[int, Any], str]:
+    def labeler(i: int, _spec: Any) -> str:  # pyright: ignore[reportUnusedParameter]
+        return f"Task {i + 1}/{total}"
+
+    return labeler
+
+
+async def multitask_gather(
+    tasks: Iterable[FuncTask[T]] | Sequence[FuncTask[T]],
+    *,
+    labeler: Callable[[int, Any], str] | None = None,
+    limit: Limit | None = None,
+    bucket_limits: dict[str, Limit] | None = None,
+    retry_settings: RetrySettings | None = None,
+    show_progress: bool = True,
+) -> list[T]:
+    """
+    Run many `FuncTask`s concurrently with shared progress UI and rate limits.
+
+    This wraps the standard pattern of creating a status context, providing a labeler,
+    and calling `gather_limited_sync` with common options.
+
+    - `labeler` can be omitted; a simple "Task X/Y" label will be used.
+    - If `limit` is not provided, defaults are taken from `global_settings()`.
+    - If `show_progress` is False, tasks are run without the status context.
+    - By default, exceptions are returned as results rather than raised (return_exceptions=True).
+    """
+
+    # Normalize tasks to a list for length and stable iteration
+    task_list: list[FuncTask[T]] = list(tasks)
+
+    # Provide a default labeler if none is supplied
+    effective_labeler: Callable[[int, Any], str] = (
+        labeler if labeler is not None else _default_labeler(len(task_list))
+    )
+
+    # Provide sensible default rate limits if none are supplied
+    effective_limit: Limit = (
+        limit
+        if limit is not None
+        else Limit(
+            rps=global_settings().limit_rps,
+            concurrency=global_settings().limit_concurrency,
+        )
+    )
+
+    if not show_progress:
+        log.warning("Running %d tasks (progress disabled)…", len(task_list))
+
+    async with multitask_status(enabled=show_progress) as status:
+        return await gather_limited_sync(
+            *task_list,
+            limit=effective_limit,
+            bucket_limits=bucket_limits,
+            status=status,
+            labeler=effective_labeler,
+            retry_settings=retry_settings,
+        )