kash-shell 0.3.35__tar.gz → 0.3.36__tar.gz

{kash_shell-0.3.35 → kash_shell-0.3.36}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier. Do not edit manually.
-_commit: v0.2.14
+_commit: v0.2.19
 _src_path: gh:jlevy/simple-modern-uv
 package_author_email: joshua@cal.berkeley.edu
 package_author_name: Joshua Levy

{kash_shell-0.3.35 → kash_shell-0.3.36}/.cursor/rules/general.mdc

@@ -7,7 +7,7 @@ alwaysApply: true
 
 **Your fundamental responsibility:** Remember you are a senior engineer and have a
 serious responsibility to be clear, factual, think step by step and be systematic,
-express expert opinion, and make use of the user's attention wisely.
+express expert opinion, and make use of the user’s attention wisely.
 
 **Rules must be followed:** It is your responsibility to carefully read these rules as
 well as Python or other language-specific rules included here.
@@ -22,19 +22,19 @@ Therefore:
   confirmation.
 
 - If you can think of a much better approach that the user requests, be sure to mention
-  it. It's your responsibility to suggest approaches that lead to better, simpler
+  it. It’s your responsibility to suggest approaches that lead to better, simpler
   solutions.
 
-- Give thoughtful opinions on better/worse approaches, but NEVER say "great idea!"
-  or "good job" or other compliments, encouragement, or non-essential banter.
+- Give thoughtful opinions on better/worse approaches, but NEVER say “great idea!”
+  or “good job” or other compliments, encouragement, or non-essential banter.
   Your job is to give expert opinions and to solve problems, not to motivate the user.
 
 - Avoid gratuitous enthusiasm or generalizations.
-  Use thoughtful comparisons like saying which code is "cleaner" but don't congratulate
+  Use thoughtful comparisons like saying which code is “cleaner” but don’t congratulate
   yourself. Avoid subjective descriptions.
-  For example, don't say "I've meticulously improved the code and it is in great shape!"
+  For example, don’t say “I’ve meticulously improved the code and it is in great shape!”
   That is useless generalization.
-  Instead, specifically say what you've done, e.g., "I've added types, including
+  Instead, specifically say what you’ve done, e.g., "I’ve added types, including
   generics, to all the methods in `Foo` and fixed all linter errors."
 
 # General Coding Guidelines
@@ -49,17 +49,17 @@ Therefore:
 - DO NOT repeat in comments what is obvious from the names of functions or variables or
   types.
 
-- DO NOT include comments that reflect what you did, such as "Added this function" as
+- DO NOT include comments that reflect what you did, such as “Added this function” as
   this is meaningless to anyone reading the code later.
   (Instead, describe in your message to the user any other contextual information.)
 
-- DO NOT use fancy or needlessly decorated headings like "===== MIGRATION TOOLS ====="
+- DO NOT use fancy or needlessly decorated headings like “===== MIGRATION TOOLS =====”
   in comments
 
 - DO NOT number steps in comments.
   These are hard to maintain if the code changes.
-  NEVER DO THIS: "// Step 3: Fetch the data from the cache"\
-  This is fine: "// Now fetch the data from the cache"
+  NEVER DO THIS: “// Step 3: Fetch the data from the cache”\
+  This is fine: “// Now fetch the data from the cache”
 
 - DO NOT use emojis or special unicode characters like ① or • or – or — in comments.
 

{kash_shell-0.3.35 → kash_shell-0.3.36}/.cursor/rules/python.mdc

@@ -87,7 +87,7 @@ Always use full type annotations, generics, and other modern practices.
 - Use pathlib `Path` instead of strings.
   Use `Path(filename).read_text()` instead of two-line `with open(...)` blocks.
 
-- Use strif's `atomic_output_file` context manager when writing files to ensure output
+- Use strif’s `atomic_output_file` context manager when writing files to ensure output
   files are written atomically.
 
 ## Use Modern Python Practices
@@ -112,7 +112,7 @@ Always use full type annotations, generics, and other modern practices.
 
 - You can run such individual tests with `uv run pytest -s src/.../path/to/test`
 
-- Don't add docs to assertions unless it's not obvious what they're checking - the
+- Don’t add docs to assertions unless it’s not obvious what they’re checking - the
   assertion appears in the stack trace.
   Do NOT write `assert x == 5, "x should be 5"`. Do NOT write `assert x == 5 # Check if
   x is 5`. That is redundant.
@@ -122,7 +122,7 @@ Always use full type annotations, generics, and other modern practices.
   assertions that confirm the value of a constant setting.
 
 - NEVER write `assert False`. If a test reaches an unexpected branch and must fail
-  explicitly, `raise AssertionError("Explanation")` instead.
+  explicitly, `raise AssertionError("Some explanation")` instead.
   This is best typical best practice in Python since assertions can be removed with
   optimization.
 
@@ -132,6 +132,21 @@ Always use full type annotations, generics, and other modern practices.
   This is also preferable because then simple tests have no explicit pytest dependencies
   and can be placed in code anywhere.
 
+- DO NOT write trivial tests that test something we know already works, like
+  instantiating a Pydantic object.
+
+  ```python
+  class Link(BaseModel):
+    url: str
+    title: str = None
+  
+  # DO NOT write tests like this. They are trivial and only create clutter!
+  def test_link_model():
+    link = Link(url="https://example.com", title="Example")
+    assert link.url == "https://example.com"
+    assert link.title == "Example"
+  ```
+
 ## Types and Type Annotations
 
 - Use modern union syntax: `str | None` instead of `Optional[str]`, `dict[str]` instead
@@ -142,7 +157,7 @@ Always use full type annotations, generics, and other modern practices.
 - Use modern enums like `StrEnum` if appropriate.
 
 - One exception to common practice on enums: If an enum has many values that are
-  strings, and they have a literal value as a string (like in a JSON protocol), it's
+  strings, and they have a literal value as a string (like in a JSON protocol), it’s
   fine to use lower_snake_case for enum values to match the actual value.
   This is more readable than LONG_ALL_CAPS_VALUES, and you can simply set the value to
   be the same as the name for each.
@@ -228,7 +243,7 @@ Always use full type annotations, generics, and other modern practices.
 - For classes with many methods, use a concise docstring on the class that explains all
   the common information, and avoid repeating the same information on every method.
 
-- Docstrings should provide context or as concisely as possible explain "why", not
+- Docstrings should provide context or as concisely as possible explain “why”, not
   obvious details evident from the class names, function names, parameter names, and
   type annotations.
 
@@ -240,10 +255,10 @@ Always use full type annotations, generics, and other modern practices.
   name, variable name, or types.
   That is silly and obvious and makes the code longer for no reason.
 
-- Do NOT list args and return values if they're obvious.
+- Do NOT list args and return values if they’re obvious.
   In the above examples, you do not need and `Arguments:` or `Returns:` section, since
-  their meaning as obvious from context.
-  do list these if there are many arguments and their meaning isn't clear.
+  sections as it is obvious from context.
+  do list these if there are many arguments and their meaning isn’t clear.
   If it returns a less obvious type like a tuple, do explain in the pydoc.
 
 - Exported/public variables, functions, or methods SHOULD have concise docstrings.

{kash_shell-0.3.35 → kash_shell-0.3.36}/.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           # Update this as needed:
-          version: "0.7.13"
+          version: "0.9.5"
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 

{kash_shell-0.3.35 → kash_shell-0.3.36}/.github/workflows/publish.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Install uv (official Astral action)
         uses: astral-sh/setup-uv@v5
         with:
-          version: "0.7.13"
+          version: "0.9.5"
           enable-cache: true
           python-version: "3.12"
 

{kash_shell-0.3.35 → kash_shell-0.3.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kash-shell
-Version: 0.3.35
+Version: 0.3.36
 Summary: The knowledge agent shell (core)
 Project-URL: Repository, https://github.com/jlevy/kash-shell
 Author-email: Joshua Levy <joshua@cal.berkeley.edu>

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/exec/llm_transforms.py

@@ -29,6 +29,7 @@ def windowed_llm_transform(
     windowing: WindowSettings | None,
     diff_filter: DiffFilter | None = None,
     check_no_results: bool = True,
+    enable_web_search: bool = False,
 ) -> TextDoc:
     def doc_transform(input_doc: TextDoc) -> TextDoc:
         return TextDoc.from_text(
@@ -41,6 +42,7 @@ def windowed_llm_transform(
                     input=input_doc.reassemble(),
                     body_template=template,
                     check_no_results=check_no_results,
+                    enable_web_search=enable_web_search,
                 ).content
             )
         )
@@ -67,6 +69,7 @@ def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: boo
             input_str,
             options.windowing,
             diff_filter=options.diff_filter,
+            enable_web_search=options.enable_web_search,
         ).reassemble()
     else:
         log.info(
@@ -81,6 +84,7 @@ def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: boo
             body_template=options.body_template,
             input=input_str,
             check_no_results=check_no_results,
+            enable_web_search=options.enable_web_search,
         ).content
 
     return result_str

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/file_storage/file_store.py

@@ -485,6 +485,9 @@ class FileStore(Workspace):
         If `with_sidematter` is true, will copy any sidematter files (metadata/assets) to
         the destination.
         """
+        # TODO: Make sure importing a text item that already has
+        # frontmatter doesn't accidentally duplicate the frontmatter
+
         from kash.file_storage.item_file_format import read_item
         from kash.web_content.canon_url import canonicalize_url
 
@@ -531,6 +534,7 @@ class FileStore(Workspace):
                 # This will read the file with or without frontmatter.
                 # We are importing so we want to drop the external path so we save the body.
                 item = read_item(path, self.base_dir)
+                log.info("Imported text item: %s", item)
                 item.external_path = None
 
                 if item.type and as_type and item.type != as_type:

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/llm_utils/llm_completion.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import time
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from flowmark import Wrap, fill_text
 from funlog import format_duration, log_calls
@@ -51,6 +51,7 @@ class LLMCompletionResult:
     message: LiteLLMMessage
     content: str
     citations: CitationList | None
+    tool_calls: list[dict[str, Any]] | None = None
 
     @property
     def content_with_citations(self) -> str:
@@ -59,40 +60,111 @@ class LLMCompletionResult:
             content = content + "\n\n" + self.citations.as_markdown_footnotes()
         return content
 
+    @property
+    def has_tool_calls(self) -> bool:
+        """Check if the response contains tool calls."""
+        return bool(self.tool_calls)
+
+    @property
+    def tool_call_names(self) -> list[str]:
+        """Get list of tool names that were called."""
+        if not self.tool_calls:
+            return []
+        names = []
+        for call in self.tool_calls:
+            # Handle both LiteLLM objects and dict representations
+            if hasattr(call, "function") and hasattr(getattr(call, "function", None), "name"):
+                # LiteLLM object format
+                names.append(f"{call.function.name}()")  # pyright: ignore[reportAttributeAccessIssue]
+            elif isinstance(call, dict) and call.get("function", {}).get("name"):
+                # Dict format
+                names.append(f"{call['function']['name']}()")
+            else:
+                names.append(str(call))
+        return names
+
 
 @log_calls(level="info")
 def llm_completion(
     model: LLMName,
     messages: list[dict[str, str]],
     save_objects: bool = True,
-    response_format: dict | type[BaseModel] | None = None,
+    response_format: dict[str, Any] | type[BaseModel] | None = None,
+    tools: list[dict[str, Any]] | None = None,
+    enable_web_search: bool = False,
     **kwargs,
 ) -> LLMCompletionResult:
     """
     Perform an LLM completion with LiteLLM.
+
+    Args:
+        model: The LLM model to use
+        messages: Chat messages
+        save_objects: Whether to save chat history
+        response_format: Response format specification
+        tools: List of tools available for function calling (e.g., web_search)
+        enable_web_search: If True, automatically add web search tools for the model
+        **kwargs: Additional LiteLLM parameters
     """
-    import litellm
     from litellm.types.utils import Choices, ModelResponse
 
     init_litellm()
 
+    # Prepare completion parameters
+    completion_params = {
+        "model": model.litellm_name,
+        "messages": messages,
+        **kwargs,
+    }
+
+    # Auto-enable web search if requested
+    if enable_web_search:
+        import litellm
+
+        if litellm.supports_web_search(model=model.litellm_name):
+            log.message("Enabling web search for model %s", model.litellm_name)
+            completion_params["web_search_options"] = {"search_context_size": "medium"}
+        else:
+            log.warning("Web search requested but not supported by model %s", model.litellm_name)
+
     chat_history = ChatHistory.from_dicts(messages)
+
+    # Enhanced logging to detect tool use
+    tools_info = f", {len(tools)} tools" if tools else ", no tools"
     log.info(
-        "Calling LLM completion from %s on %s, response_format=%s",
+        "Calling LLM completion from %s on %s, response_format=%s%s",
         model.litellm_name,
         chat_history.size_summary(),
         response_format,
+        tools_info,
     )
 
+    if tools:
+        tool_names = []
+        for tool in tools:
+            if tool.get("type") == "function":
+                tool_names.append(tool.get("function", {}).get("name", "unknown"))
+            elif tool.get("type") == "native_web_search":
+                tool_names.append("native_web_search")
+            else:
+                tool_names.append(tool.get("type", "unknown"))
+
+        log.message("Tools enabled: %s", tool_names)
+
     start_time = time.time()
+
+    if response_format:
+        completion_params["response_format"] = response_format
+
+    if tools:
+        completion_params["tools"] = tools
+        log.info("Enabling function calling with %d tools", len(tools))
+
+    import litellm
+
     llm_output = cast(
         ModelResponse,
-        litellm.completion(
-            model.litellm_name,
-            messages=messages,
-            response_format=response_format,
-            **kwargs,
-        ),  # pyright: ignore
+        litellm.completion(**completion_params),  # pyright: ignore
     )
     elapsed = time.time() - start_time
 
@@ -100,23 +172,47 @@ def llm_completion(
 
     message = choices.message
 
+    # Extract tool calls from the response
+    tool_calls = getattr(message, "tool_calls", None)
+    tool_calls_list = list(tool_calls) if tool_calls else None
+
     # Just sanity checking and logging.
     content = choices.message.content
     if not content or not isinstance(content, str):
         raise ApiResultError(f"LLM completion failed: {model.litellm_name}: {llm_output}")
 
+    # Create the result object with tool calls
+    citations = llm_output.get("citations", None)
+    result = LLMCompletionResult(
+        message=message,
+        content=content,
+        citations=CitationList(citations=citations) if citations else None,
+        tool_calls=tool_calls_list,
+    )
+
+    # Log tool calls if present
+    if result.has_tool_calls:
+        tool_count = len(result.tool_calls or [])
+        log.message("LLM executed %d function calls: %s", tool_count, result.tool_call_names)
+        log.message(
+            "⚠️  Function calls require implementation - LLM requested tools but no handlers are implemented"
+        )
+
+    # Performance logging
     total_input_len = sum(len(m["content"]) for m in messages)
     speed = len(content) / elapsed
+    tool_count = len(result.tool_calls or []) if result.has_tool_calls else 0
+    tool_info = f", {tool_count} tool calls" if result.has_tool_calls else ""
     log.info(
         f"{EMOJI_TIMING} LLM completion from {model.litellm_name} in {format_duration(elapsed)}: "
         f"input {total_input_len} chars in {len(messages)} messages, output {len(content)} chars "
-        f"({speed:.0f} char/s)"
+        f"({speed:.0f} char/s){tool_info}"
     )
 
-    citations = llm_output.get("citations", None)
-
     if save_objects:
         metadata = {"citations": citations} if citations else {}
+        if result.has_tool_calls:
+            metadata["tool_calls"] = len(result.tool_calls or [])
         chat_history.messages.append(
             ChatMessage(role=ChatRole.assistant, content=content, metadata=metadata)
         )
@@ -128,11 +224,7 @@ def llm_completion(
             file_ext="yml",
         )
 
-    return LLMCompletionResult(
-        message=message,
-        content=content,
-        citations=CitationList(citations=citations) if citations else None,
-    )
+    return result
 
 
 def llm_template_completion(
@@ -143,7 +235,9 @@ def llm_template_completion(
     previous_messages: list[dict[str, str]] | None = None,
     save_objects: bool = True,
     check_no_results: bool = True,
-    response_format: dict | type[BaseModel] | None = None,
+    response_format: dict[str, Any] | type[BaseModel] | None = None,
+    tools: list[dict[str, Any]] | None = None,
+    enable_web_search: bool = False,
     **kwargs,
 ) -> LLMCompletionResult:
     """
@@ -169,6 +263,8 @@ def llm_template_completion(
         ],
         save_objects=save_objects,
         response_format=response_format,
+        tools=tools,
+        enable_web_search=enable_web_search,
         **kwargs,
     )
 

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/llm_utils/llms.py

@@ -28,22 +28,23 @@ class LLM(LLMName, Enum):
     gpt_4_1 = LLMName("gpt-4.1")
     gpt_4o = LLMName("gpt-4o")
     gpt_4o_mini = LLMName("gpt-4o-mini")
+    gpt_4o_search_preview = LLMName("gpt-4o-search-preview")
     gpt_4 = LLMName("gpt-4")
     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
+    # https://docs.claude.com/en/docs/about-claude/models
 
-    claude_4_1_opus = LLMName("claude-opus-4-1")
-    claude_4_opus = LLMName("claude-opus-4-20250514")
-    claude_4_sonnet = LLMName("claude-sonnet-4-20250514")
-    claude_3_7_sonnet = LLMName("claude-3-7-sonnet-latest")
-    claude_3_5_haiku = LLMName("claude-3-5-haiku-latest")
+    claude_sonnet_4_5 = LLMName("claude-sonnet-4-5-20250929")
+    claude_haiku_4_5 = LLMName("claude-haiku-4-5-20251001")
+    claude_opus_4_1 = LLMName("claude-opus-4-1-20250805")
+    claude_sonnet_4 = LLMName("claude-sonnet-4-20250514")
+    claude_opus_4 = LLMName("claude-opus-4-20250514")
 
     # https://ai.google.dev/gemini-api/docs/models
     gemini_2_5_pro = LLMName("gemini/gemini-2.5-pro")
     gemini_2_5_flash = LLMName("gemini/gemini-2.5-flash")
-    gemini_2_5_flash_lite = LLMName("gemini-2.5-flash-lite-preview-06-17")
+    gemini_2_5_flash_lite = LLMName("gemini/gemini-2.5-flash-lite")
 
     # https://docs.x.ai/docs/models
     xai_grok_3 = LLMName("xai/grok-3")

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/model/actions_model.py

@@ -171,6 +171,7 @@ class LLMOptions:
     body_template: MessageTemplate = MessageTemplate("{body}")
     windowing: WindowSettings = WINDOW_NONE
     diff_filter: DiffFilter | None = None
+    enable_web_search: bool = False
 
     def updated_with(self, param_name: str, value: Any) -> LLMOptions:
         """Update option from an action parameter."""
@@ -543,8 +544,8 @@ class Action(ABC):
     def preassemble_result(self, context: ActionContext) -> ActionResult | None:
         """
         Actions can have a separate preliminary step to pre-assemble outputs. This allows
-        us to determine the title and types for the output items and check if they were
-        already generated before running slow or expensive actions.
+        us to determine thew expected shape of the expected output and check if it already
+        exists.
 
         For now, this only applies to actions with a single output, when `self.cacheable`
         is True.
@@ -568,7 +569,10 @@ class Action(ABC):
                     self.name,
                 )
                 output_type = ItemType.doc
-            primary_output = primary_input.derived_copy(context, 0, type=output_type)
+            output_format = context.action.output_format or primary_input.format
+            primary_output = primary_input.derived_copy(
+                context, 0, type=output_type, format=output_format
+            )
             log.info("Preassembled output: source %s, %s", primary_output.source, primary_output)
             return ActionResult([primary_output])
         else:

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/model/items_model.py

@@ -193,9 +193,16 @@ class ItemId:
         from kash.web_content.canon_url import canonicalize_url
 
         item_id = None
-        if item.type == ItemType.resource and item.format == Format.url and item.url:
+        if (
+            item.type == ItemType.resource
+            and item.format == Format.url
+            and item.url
+            and not item.source
+        ):
+            # This is a plain URL resource, so its identity is its URL.
             item_id = ItemId(item.type, IdType.url, canonicalize_url(item.url))
         elif item.type == ItemType.concept and item.title:
+            # This is a concept, so its identity is its title.
             item_id = ItemId(item.type, IdType.concept, canonicalize_concept(item.title))
         elif item.source and item.source.cacheable and item.source.operation.has_known_inputs:
             # We know the source of this and if the action was cacheable, we can create

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/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.gpt_5
-DEFAULT_STRUCTURED_LLM = LLM.gpt_5
-DEFAULT_STANDARD_LLM = LLM.gpt_5
-DEFAULT_FAST_LLM = LLM.gpt_5_mini
+DEFAULT_CAREFUL_LLM = LLM.claude_sonnet_4_5
+DEFAULT_STRUCTURED_LLM = LLM.claude_sonnet_4_5
+DEFAULT_STANDARD_LLM = LLM.claude_sonnet_4_5
+DEFAULT_FAST_LLM = LLM.claude_haiku_4_5
 
 
 # Parameters set globally such as in the workspace.

{kash_shell-0.3.35 → kash_shell-0.3.36}/src/kash/web_gen/templates/youtube_webpage.html.jinja

@@ -1,8 +1,9 @@
 {% extends "simple_webpage.html.jinja" %}
 
 {#
-  Extends the simple page with a right-side YouTube popover player.
-  Usage: pass page_template="youtube_webpage.html.jinja" to simple_webpage_render.
+  Extends the simple page with YouTube popover player.
+  Safe to use instead of simple_webpage.html.jinja since it only adds
+  functionality for YouTube if applicable.
 #}
 
 {% block custom_styles %}