banks 2.1.3__tar.gz → 2.3.0__tar.gz

{banks-2.1.3 → banks-2.3.0}/.github/workflows/test.yml

@@ -34,7 +34,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4
@@ -72,7 +72,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4
@@ -95,7 +95,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

{banks-2.1.3 → banks-2.3.0}/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Banks is a Python prompt programming language and templating system for LLM applications. It provides a Jinja2-based template engine with specialized extensions and filters for creating dynamic prompts, managing chat messages, handling multimodal content (images/audio), and integrating with various LLM providers through LiteLLM.
+Banks is a Python prompt programming language and templating system for LLM applications. It provides a Jinja2-based template engine with specialized extensions and filters for creating dynamic prompts, managing chat messages, handling multimodal content (images/audio/video/documents), and integrating with various LLM providers through LiteLLM.
 
 ## Development Commands
 
@@ -28,7 +28,7 @@ Banks is a Python prompt programming language and templating system for LLM appl
 ### Environment Management
 - All commands use Hatch environments with automatic dependency management
 - Use `uv` as the installer for faster dependency resolution
-- Python 3.9+ supported across multiple versions (3.9-3.13)
+- Python 3.10+ supported across multiple versions (3.10-3.14)
 
 ## Architecture Overview
 
@@ -42,7 +42,7 @@ Banks is a Python prompt programming language and templating system for LLM appl
 
 **Type System** (`src/banks/types.py`):
 - `ChatMessage`: Core chat message structure with role and content
-- `ContentBlock`: Handles different content types (text, image_url, audio) with optional cache control
+- `ContentBlock`: Handles different content types (text, image_url, audio, video, document) with optional cache control
 - `Tool`: Function calling support with automatic schema generation from Python callables
 - `CacheControl`: Anthropic-style prompt caching metadata
 
@@ -67,6 +67,8 @@ Banks is a Python prompt programming language and templating system for LLM appl
 **Core Filters** (`src/banks/filters/`):
 - `image`: Convert file paths/URLs to base64-encoded image content blocks
 - `audio`: Convert audio files to base64-encoded audio content blocks  
+- `video`: Convert video files to base64-encoded video content blocks
+- `document`: Convert documents (PDF, TXT, HTML, CSS, XML, CSV, RTF, JS, JSON) to base64-encoded content blocks
 - `cache_control`: Add Anthropic cache control metadata to content blocks
 - `tool`: Convert Python callables to LLM function call schemas
 - `lemmatize`: Text lemmatization using simplemma
@@ -95,7 +97,7 @@ Banks is a Python prompt programming language and templating system for LLM appl
 4. Caching layer prevents re-rendering identical contexts
 
 ### Multimodal Content Handling
-- Images/audio converted to base64 during filter application
+- Images/audio/video/documents converted to base64 during filter application
 - Content blocks maintain type safety and metadata
 - Cache control integrated at content block level
 

{banks-2.1.3 → banks-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banks
-Version: 2.1.3
+Version: 2.3.0
 Summary: A prompt programming language
 Project-URL: Documentation, https://github.com/masci/banks#readme
 Project-URL: Issues, https://github.com/masci/banks/issues
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.9
@@ -125,11 +126,11 @@ print(p.chat_messages({"persona": "helpful assistant"}))
 # [
 #   ChatMessage(role='system', content=[
 #      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='You are a helpful assistant.', 
-#                  image_url=None, input_audio=None)
+#                  image_url=None, input_audio=None, input_video=None, input_document=None)
 #   ], tool_call_id=None, name=None), 
 #   ChatMessage(role='user', content=[
 #      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='Hello, how are you?', 
-#                  image_url=None, input_audio=None)
+#                  image_url=None, input_audio=None, input_video=None, input_document=None)
 #   ], tool_call_id=None, name=None)
 # ]
 ```

{banks-2.1.3 → banks-2.3.0}/README.md

@@ -94,11 +94,11 @@ print(p.chat_messages({"persona": "helpful assistant"}))
 # [
 #   ChatMessage(role='system', content=[
 #      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='You are a helpful assistant.', 
-#                  image_url=None, input_audio=None)
+#                  image_url=None, input_audio=None, input_video=None, input_document=None)
 #   ], tool_call_id=None, name=None), 
 #   ChatMessage(role='user', content=[
 #      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='Hello, how are you?', 
-#                  image_url=None, input_audio=None)
+#                  image_url=None, input_audio=None, input_video=None, input_document=None)
 #   ], tool_call_id=None, name=None)
 # ]
 ```

{banks-2.1.3 → banks-2.3.0}/docs/examples.md

@@ -3,6 +3,7 @@
 - [Create a blog writing prompt](#create-a-blog-writing-prompt)
 - [Create a summarizer prompt](#create-a-summarizer-prompt)
 - [Lemmatize text while processing a template](#lemmatize-text-while-processing-a-template)
+- [Convert a JSON-like object into XML while processing the template](#convert-a-json-like-object-into-xml-while-processing-the-template)
 - [Use a LLM to generate a text while rendering a prompt](#use-a-llm-to-generate-a-text-while-rendering-a-prompt)
 - [Render a prompt template as chat messages](#render-a-prompt-template-as-chat-messages)
 - [Use prompt caching from Anthropic](#use-prompt-caching-from-anthropic)
@@ -135,6 +136,57 @@ the cat be run
 Summary:
 ```
 
+## Convert a JSON-like object into XML while processing the template
+
+Banks has built-in support for filtering JSON-like objects (Pydantic `BaseModel` subclasses, dictionaries, deserializable strings) and returning an XML string. 
+
+Here is an example of how you can use it:
+
+```python
+from banks import Prompt
+from pydantic import BaseModel
+from typing import Dict
+
+prompt_template = """
+Please extract the contact details from this user:
+
+{{ data | to_xml }}
+
+Contact details:
+"""
+
+class User(BaseModel):
+    username: str
+    account_id: str
+    registered_at: str
+    email: str
+    phone_number: str
+    social_media_accounts: Dict[str, str]
+
+user = User(username="example", account_id="0000", registered_at="10-25-2024", email="example@email.com", phone_number="0123456789", social_media_accounts={"BlueSky": "@example.com"})
+
+p = Prompt(prompt_template)
+print(p.text({"data": user}))
+```
+
+This will output:
+
+```text
+Please extract the contact details from this user:
+
+<user>
+	<username>example</username>
+	<account_id>0000</account_id>
+	<registered_at>10-25-2024</registered_at>
+	<email>example@email.com</email>
+	<phone_number>0123456789</phone_number>
+	<social_media_accounts>{'BlueSky': '@example.com'}</social_media_accounts>
+</user>
+
+
+Contact details:
+```
+
 ## Use a LLM to generate a text while rendering a prompt
 
 Sometimes it might be useful to ask another LLM to generate examples for you in a

{banks-2.1.3 → banks-2.3.0}/pyproject.toml

@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
@@ -65,7 +66,7 @@ cov = ["test-cov", "cov-report"]
 docs = "mkdocs {args:build}"
 
 [[tool.hatch.envs.all.matrix]]
-python = ["3.9", "3.10", "3.11", "3.12", "3.13"]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
 [tool.hatch.envs.lint]
 detached = false                                                              # Normally the linting env can be detached, but mypy doesn't install all the stubs we need
@@ -199,7 +200,7 @@ max-args = 10
 asyncio_default_fixture_loop_scope = "function"
 markers = ["e2e"]
 filterwarnings = [
-    # Dilence litellm warning coming from their Pydantic config.
+    # Silence litellm warning coming from their Pydantic config.
     # This assumes our use of Pydantic is correct :)
     "ignore:Support for class-based `config` is deprecated",
 ]

{banks-2.1.3 → banks-2.3.0}/src/banks/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "2.1.3"
+__version__ = "2.3.0"

{banks-2.1.3 → banks-2.3.0}/src/banks/config.py

@@ -28,9 +28,12 @@ class _BanksConfig:
             return original_value
 
         # Convert string from env var to the actual type
-        t = super().__getattribute__("__annotations__")[name]
+        annotations = getattr(type(self), "__annotations__", {})
+        t = annotations.get(name, type(original_value))
         if t is bool:
             return strtobool(read_value)
+        if t is Any:
+            return read_value
 
         return t(read_value)
 

{banks-2.1.3 → banks-2.3.0}/src/banks/env.py

@@ -4,7 +4,7 @@
 from jinja2 import Environment, select_autoescape
 
 from .config import config
-from .filters import audio, cache_control, image, lemmatize, tool
+from .filters import audio, cache_control, document, image, lemmatize, tool, video, xml
 
 
 def _add_extensions(_env):
@@ -38,5 +38,8 @@ env.filters["image"] = image
 env.filters["lemmatize"] = lemmatize
 env.filters["tool"] = tool
 env.filters["audio"] = audio
+env.filters["video"] = video
+env.filters["document"] = document
+env.filters["to_xml"] = xml
 
 _add_extensions(env)

{banks-2.1.3 → banks-2.3.0}/src/banks/errors.py

@@ -14,7 +14,7 @@ class CanaryWordError(Exception):
 
 
 class PromptNotFoundError(Exception):
-    """The prompt was now found in the registry."""
+    """The prompt was not found in the registry."""
 
 
 class InvalidPromptError(Exception):

{banks-2.1.3 → banks-2.3.0}/src/banks/extensions/completion.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 import importlib
 import json
-from typing import cast
+from typing import TYPE_CHECKING, Any, Callable, cast
 
 from jinja2 import TemplateSyntaxError, nodes
 from jinja2.ext import Extension
@@ -12,6 +12,8 @@ from pydantic import ValidationError
 from banks.errors import InvalidPromptError, LLMError
 from banks.types import ChatMessage, Tool
 
+if TYPE_CHECKING:
+    from litellm.types.utils import ChatCompletionMessageToolCall
 SUPPORTED_KWARGS = ("model",)
 LITELLM_INSTALL_MSG = "litellm is not installed. Please install it with `pip install litellm`."
 
@@ -74,7 +76,19 @@ class CompletionExtension(Extension):
             return nodes.CallBlock(self.call_method("_do_completion_async", args), [], [], body).set_lineno(lineno)
         return nodes.CallBlock(self.call_method("_do_completion", args), [], [], body).set_lineno(lineno)
 
-    def _get_tool_callable(self, tools, tool_call):
+    def _get_tool_callable(self, tools: list[Tool], tool_call: "ChatCompletionMessageToolCall") -> Callable[..., Any]:
+        """Get the callable function for a tool call.
+
+        Args:
+            tools: List of available tools
+            tool_call: The tool call from the LLM response
+
+        Returns:
+            The callable function
+
+        Raises:
+            ValueError: If the function is not found in available tools
+        """
         for tool in tools:
             if tool.function.name == tool_call.function.name:
                 module_name, func_name = tool.import_path.rsplit(".", maxsplit=1)

{banks-2.1.3 → banks-2.3.0}/src/banks/filters/__init__.py

@@ -3,8 +3,11 @@
 # SPDX-License-Identifier: MIT
 from .audio import audio
 from .cache_control import cache_control
+from .document import document
 from .image import image
 from .lemmatize import lemmatize
 from .tool import tool
+from .video import video
+from .xml import xml
 
-__all__ = ("cache_control", "image", "lemmatize", "tool", "audio")
+__all__ = ("cache_control", "image", "lemmatize", "tool", "audio", "video", "document", "xml")

banks-2.3.0/src/banks/filters/audio.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+import re
+from pathlib import Path
+from typing import cast
+from urllib.parse import urlparse
+
+from banks.types import AudioFormat, ContentBlock, InputAudio
+
+BASE64_AUDIO_REGEX = re.compile(r"audio\/.*;base64,.*")
+
+
+def _is_url(string: str) -> bool:
+    """Check if a string is a URL."""
+    result = urlparse(string)
+    if not result.scheme:
+        return False
+
+    if not result.netloc:
+        # The only valid format when netloc is empty is base64 data urls
+        return all([result.scheme == "data", BASE64_AUDIO_REGEX.match(result.path)])
+
+    return True
+
+
+def _get_audio_format_from_url(url: str) -> AudioFormat:
+    """Extract audio format from URL.
+
+    Tries to determine format from URL path or defaults to mp3.
+    """
+    parsed = urlparse(url)
+    path = parsed.path.lower()
+    for fmt in ("mp3", "wav", "m4a", "webm", "ogg", "flac"):
+        if path.endswith(f".{fmt}"):
+            return cast(AudioFormat, fmt)
+    # Default to mp3 if format cannot be determined
+    return "mp3"
+
+
+def audio(value: str) -> str:
+    """Wrap the filtered value into a ContentBlock of type audio.
+
+    The resulting ChatMessage will have the field `content` populated with a list of ContentBlock objects.
+
+    Supports both file paths and URLs (including data URLs).
+
+    Example:
+        ```jinja
+        {{ "path/to/audio/file.mp3" | audio }}
+        {{ "https://example.com/audio.mp3" | audio }}
+        ```
+    """
+    if _is_url(value):
+        audio_format = _get_audio_format_from_url(value)
+        input_audio = InputAudio.from_url(value, audio_format)
+    else:
+        input_audio = InputAudio.from_path(Path(value))
+    block = ContentBlock.model_validate({"type": "audio", "input_audio": input_audio})
+    return f"<content_block>{block.model_dump_json()}</content_block>"

banks-2.3.0/src/banks/filters/document.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+import re
+from pathlib import Path
+from typing import cast
+from urllib.parse import urlparse
+
+from banks.types import ContentBlock, DocumentFormat, InputDocument
+
+BASE64_DOCUMENT_REGEX = re.compile(r"(text|application)\/.*;base64,.*")
+
+
+def _is_url(string: str) -> bool:
+    """Check if a string is a URL."""
+    result = urlparse(string)
+    if not result.scheme:
+        return False
+
+    if not result.netloc:
+        # The only valid format when netloc is empty is base64 data urls
+        return all([result.scheme == "data", BASE64_DOCUMENT_REGEX.match(result.path)])
+
+    return True
+
+
+def _get_document_format_from_url(url: str) -> DocumentFormat:
+    """Extract document format from URL.
+
+    Tries to determine format from URL path or defaults to pdf.
+    """
+    parsed = urlparse(url)
+    path = parsed.path.lower()
+    # Gemini supported file types https://ai.google.dev/gemini-api/docs/file-input-methods
+    # text/html
+    # text/css
+    # text/plain
+    # text/xml
+    # text/scv
+    # text/rtf
+    # text/javascript
+    # application/json
+    # application/pdf
+
+    # Claude supported file types
+    # application/pdf
+    # text/plain
+
+    # OpenAI supported file types
+    # application/pdf
+
+    for fmt in (
+        "pdf",
+        "html",
+        "htm",
+        "xhtml",
+        "css",
+        "txt",
+        "md",
+        "markdown",
+        "rst",
+        "xml",
+        "csv",
+        "rtf",
+        "js",
+        "mjs",
+        "cjs",
+        "javascript",
+        "json",
+    ):
+        if path.endswith(f".{fmt}"):
+            return cast(DocumentFormat, fmt)
+    # Default to pdf if format cannot be determined
+    return "pdf"
+
+
+def document(value: str) -> str:
+    """Wrap the filtered value into a ContentBlock of type document.
+
+    The resulting ChatMessage will have the field `content` populated with a list of ContentBlock objects.
+
+    Supports both file paths and URLs (including data URLs).
+
+    Example:
+        ```jinja
+        {{ "path/to/document/file.pdf" | document }}
+        {{ "https://example.com/document.pdf" | document }}
+        ```
+    """
+    if _is_url(value):
+        document_format = _get_document_format_from_url(value)
+        input_document = InputDocument.from_url(value, document_format)
+    else:
+        input_document = InputDocument.from_path(Path(value))
+    block = ContentBlock.model_validate({"type": "document", "input_document": input_document})
+    return f"<content_block>{block.model_dump_json()}</content_block>"

{banks-2.1.3 → banks-2.3.0}/src/banks/filters/image.py

@@ -1,15 +1,25 @@
 # SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
 #
 # SPDX-License-Identifier: MIT
+import re
 from pathlib import Path
 from urllib.parse import urlparse
 
 from banks.types import ContentBlock, ImageUrl
 
+BASE64_PATH_REGEX = re.compile(r"image\/.*;base64,.*")
+
 
 def _is_url(string: str) -> bool:
     result = urlparse(string)
-    return all([result.scheme, result.netloc])
+    if not result.scheme:
+        return False
+
+    if not result.netloc:
+        # The only valid format when netloc is empty is base64 data urls
+        return all([result.scheme == "data", BASE64_PATH_REGEX.match(result.path)])
+
+    return True
 
 
 def image(value: str) -> str:

banks-2.3.0/src/banks/filters/video.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+import re
+from pathlib import Path
+from typing import cast
+from urllib.parse import urlparse
+
+from banks.types import ContentBlock, InputVideo, VideoFormat
+
+BASE64_VIDEO_REGEX = re.compile(r"video\/.*;base64,.*")
+
+
+def _is_url(string: str) -> bool:
+    """Check if a string is a URL."""
+    result = urlparse(string)
+    if not result.scheme:
+        return False
+
+    if not result.netloc:
+        # The only valid format when netloc is empty is base64 data urls
+        return all([result.scheme == "data", BASE64_VIDEO_REGEX.match(result.path)])
+
+    return True
+
+
+def _get_video_format_from_url(url: str) -> VideoFormat:
+    """Extract video format from URL.
+
+    Tries to determine format from URL path or defaults to mp4.
+    """
+    parsed = urlparse(url)
+    path = parsed.path.lower()
+
+    # Based on formats supported by Gemini https://ai.google.dev/gemini-api/docs/video-understanding
+    for fmt in ("mp4", "mpeg", "mov", "avi", "flv", "mpg", "webm", "wmv", "3gpp"):
+        if path.endswith(f".{fmt}"):
+            return cast(VideoFormat, fmt)
+    # Default to mp4 if format cannot be determined
+    return "mp4"
+
+
+def video(value: str) -> str:
+    """Wrap the filtered value into a ContentBlock of type video.
+
+    The resulting ChatMessage will have the field `content` populated with a list of ContentBlock objects.
+
+    Supports both file paths and URLs (including data URLs).
+
+    Example:
+        ```jinja
+        {{ "path/to/video/file.mp4" | video }}
+        {{ "https://example.com/video.mp4" | video }}
+        ```
+    """
+    if _is_url(value):
+        video_format = _get_video_format_from_url(value)
+        input_video = InputVideo.from_url(value, video_format)
+    else:
+        input_video = InputVideo.from_path(Path(value))
+    block = ContentBlock.model_validate({"type": "video", "input_video": input_video})
+    return f"<content_block>{block.model_dump_json()}</content_block>"

banks-2.3.0/src/banks/filters/xml.py

@@ -0,0 +1,62 @@
+import json
+import xml.etree.ElementTree as ET
+from typing import Any, Optional, Union
+from xml.dom.minidom import parseString
+
+from pydantic import BaseModel
+
+
+def _deserialize(string: str) -> Optional[dict]:
+    try:
+        return json.loads(string)
+    except json.JSONDecodeError:
+        return None
+
+
+def _prepare_dictionary(value: Union[str, BaseModel, dict[str, Any]]):
+    root_tag = "input"
+    if isinstance(value, str):
+        model: Optional[dict[str, Any]] = _deserialize(value)
+        if model is None:
+            msg = f"{value} is not deserializable"
+            raise ValueError(msg)
+    elif isinstance(value, BaseModel):
+        model = value.model_dump()
+        root_tag = value.__class__.__name__.lower()
+    elif isinstance(value, dict):
+        model = value.copy()
+        for k in value.keys():
+            if not isinstance(k, str):
+                key = str(k)
+                if isinstance(k, (int, float)):
+                    key = "_" + key
+                v = model.pop(k)
+                model[key.lower()] = v
+    else:
+        msg = f"Input can only be of type BaseModel, dictionary or deserializable string. Got {type(value)}"
+        raise ValueError(msg)
+    return model, root_tag
+
+
+def xml(value: Union[str, BaseModel, dict[str, Any]]) -> str:
+    """
+    Convert a Pydantic model, a deserializable string or a dictionary into an XML string.
+
+    Example:
+        ```jinja
+        {{'{"username": "user", "email": "example@email.com"}' | to_xml}}
+        "
+        <input>
+            <username>user</username>
+            <email>example@email.com</email>
+        </input>
+        "
+        ```
+    """
+    model, root_tag = _prepare_dictionary(value)
+    xml_model = ET.Element(root_tag)
+    for k, v in model.items():
+        sub = ET.SubElement(xml_model, k)
+        sub.text = str(v)
+    xml_str = ET.tostring(xml_model, encoding="unicode")
+    return parseString(xml_str).toprettyxml().replace('<?xml version="1.0" ?>\n', "")  # noqa: S318

{banks-2.1.3 → banks-2.3.0}/src/banks/prompt.py

@@ -81,8 +81,17 @@ class BasePrompt:
 
     @property
     def variables(self) -> set[str]:
-        ast = env.parse(self.raw)
-        return meta.find_undeclared_variables(ast)
+        try:
+            ast = env.parse(self.raw)
+            return meta.find_undeclared_variables(ast)
+        except Exception as e:
+            from jinja2 import TemplateSyntaxError
+
+            if isinstance(e, TemplateSyntaxError):
+                raise
+            # Re-raise as TemplateSyntaxError for consistency
+            msg = f"Failed to parse template: {e}"
+            raise TemplateSyntaxError(msg, 0) from e
 
     def canary_leaked(self, text: str) -> bool:
         """Returns whether the canary word is present in `text`, signalling the prompt might have leaked."""