banks 2.2.0__tar.gz → 2.4.0__tar.gz

banks-2.4.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: PyPI Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - MINOR
+          - BUGFIX
+        default: BUGFIX
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Bump version
+        run: |
+          CURRENT=$(sed -n 's/^__version__ = "\([0-9.]*\).*/\1/p' src/banks/__about__.py)
+          IFS=. read -r major minor patch <<< "$CURRENT"
+          case "${{ github.event.inputs.bump }}" in
+            BUGFIX)
+              patch=$((patch + 1))
+              ;;
+            MINOR)
+              minor=$((minor + 1))
+              patch=0
+              ;;
+            *)
+              echo "Unexpected bump type: ${{ github.event.inputs.bump }}"
+              exit 1
+              ;;
+          esac
+          VERSION="${major}.${minor}.${patch}"
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+          echo "Bumped ${CURRENT} -> ${VERSION} (${{ github.event.inputs.bump }})"
+
+      - name: Update __about__.py on default branch
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          sed -i "s/^__version__ = .*$/__version__ = \"${VERSION}\"/" src/banks/__about__.py
+          git diff --quiet && exit 0
+          git add src/banks/__about__.py
+          git commit -m "chore: set __version__ to ${VERSION} [skip ci]"
+          git push origin "${{ github.event.repository.default_branch }}"
+
+      - name: Create and push tag
+        run: |
+          git tag "v${VERSION}"
+          git push origin "v${VERSION}"
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Publish on PyPi
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          hatch build
+          hatch publish -y
+
+      - name: Create GitHub Release
+        uses: ncipollo/release-action@v1
+        with:
+          tag: v${{ env.VERSION }}
+          artifacts: "dist/*"
+          generateReleaseNotes: true

{banks-2.2.0 → banks-2.4.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.4.0/AGENTS.md

@@ -0,0 +1,218 @@
+# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## 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/video/documents), and integrating with various LLM providers through LiteLLM.
+
+## Quick Reference
+
+```bash
+# Most common commands
+hatch run test                    # Run unit tests
+hatch run lint:all                # Run all linting checks
+hatch run lint:fmt                # Auto-format code
+hatch run test tests/test_foo.py  # Run specific test file
+```
+
+## Development Commands
+
+### Testing
+- Run tests: `hatch run test`
+- Run tests with coverage: `hatch run test-cov`
+- Generate coverage report: `hatch run cov`
+- Run specific test file: `hatch run test tests/test_foo.py`
+- Run e2e tests: `hatch run test tests/e2e/` (requires API keys)
+
+### Linting and Type Checking
+- Format code: `hatch run lint:fmt`
+- Auto-fix lint issues: `hatch run lint:fix`
+- Check formatting: `hatch run lint:check`
+- Run type checking: `hatch run lint:typing`
+- Run pylint: `hatch run lint:lint`
+- Run all lint checks: `hatch run lint:all`
+
+### Documentation
+- Build docs: `hatch run docs build`
+- Serve docs locally: `hatch run docs serve` (available at http://127.0.0.1:8000/)
+
+### Environment Management
+- All commands use Hatch environments with automatic dependency management
+- Uses `uv` as the installer for faster dependency resolution
+- Python 3.9+ supported (tested on 3.10-3.14)
+
+## Architecture Overview
+
+### Core Components
+
+**Prompt Classes** (`src/banks/prompt.py`):
+- `BasePrompt`: Base class with template rendering, metadata, versioning, and caching
+- `Prompt`: Synchronous prompt rendering with `text()` and `chat_messages()` methods
+- `AsyncPrompt`: Asynchronous version (requires `BANKS_ASYNC_ENABLED=true`)
+- `PromptRegistry`: Protocol interface for prompt storage backends
+
+**Type System** (`src/banks/types.py`):
+- `ChatMessage`: Core chat message structure with role and content
+- `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
+
+**Template Environment** (`src/banks/env.py`):
+- Global Jinja2 environment with Banks-specific extensions and filters
+- Async support detection and configuration
+- Custom template loader integration
+
+**Error Types** (`src/banks/errors.py`):
+- `MissingDependencyError`: Optional dependencies not installed
+- `AsyncError`: Asyncio support misconfiguration
+- `CanaryWordError`: Canary word leaked (prompt injection detection)
+- `PromptNotFoundError`: Prompt not found in registry
+- `InvalidPromptError`: Invalid prompt format
+- `LLMError`: LLM provider errors
+
+### Extensions System
+
+**Chat Extension** (`src/banks/extensions/chat.py`):
+- `{% chat role="..." %}...{% endchat %}` blocks for structured message creation
+- Automatic conversion to `ChatMessage` objects during rendering
+
+**Completion Extension** (`src/banks/extensions/completion.py`):
+- `{% completion model="..." %}...{% endcompletion %}` for in-prompt LLM calls
+- Integrated with LiteLLM for multi-provider support
+- Function calling support within completion blocks
+
+### Filters System
+
+**Core Filters** (`src/banks/filters/`):
+- `image`: Convert file paths/URLs/bytes 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
+
+**Filter Pattern**: Filters wrap content in `<content_block>` tags and are only useful within `{% chat %}` blocks.
+
+### Registry System
+
+**Storage Backends** (`src/banks/registries/`):
+- `DirectoryTemplateRegistry`: File system-based prompt storage
+- `FileTemplateRegistry`: Single file-based storage
+- `RedisTemplateRegistry`: Redis-backed storage for distributed scenarios
+- All registries implement the `PromptRegistry` protocol
+
+### Caching System
+
+**Render Cache** (`src/banks/cache.py`):
+- `RenderCache`: Protocol interface for caching rendered prompts
+- `DefaultCache`: In-memory cache using pickle-serialized context as key
+- Prevents re-rendering identical template + context combinations
+
+### Configuration
+
+**Config System** (`src/banks/config.py`):
+- Environment variable-based configuration with `BANKS_` prefix
+- `BANKS_ASYNC_ENABLED`: Enable async template rendering (must be set before import)
+- `BANKS_USER_DATA_PATH`: Custom user data directory
+
+## Key Development Patterns
+
+### Template Rendering Flow
+1. Templates parsed by Jinja2 environment with Banks extensions
+2. Chat blocks converted to JSON during rendering
+3. `chat_messages()` parses JSON back to `ChatMessage` objects
+4. Caching layer prevents re-rendering identical contexts
+
+### Multimodal Content Handling
+- Images/audio/video/documents converted to base64 during filter application
+- Filters accept file paths, URLs, or raw bytes
+- Content blocks maintain type safety and metadata
+- Cache control integrated at content block level
+
+### Function Calling Integration
+- Python functions automatically converted to LLM schemas via introspection
+- Docstring parsing for parameter descriptions
+- Type annotations converted to JSON Schema
+
+### Async Support Architecture
+- Global environment state requires async decision at import time
+- `BANKS_ASYNC_ENABLED` must be set before importing banks modules
+- `AsyncPrompt` provides `await`-able rendering methods
+
+## Testing
+
+### Test Markers
+- `@pytest.mark.e2e`: End-to-end tests requiring external services
+- `@pytest.mark.redis`: Tests requiring a running Redis instance
+
+### Required Environment Variables for E2E Tests
+- `OPENAI_API_KEY`: For OpenAI-based tests
+- `ANTHROPIC_API_KEY`: For Anthropic-based tests
+
+### Test Data
+- Test fixtures in `tests/data/` (images, audio, video, PDFs)
+- Template examples in `tests/templates/`
+
+### Running Specific Tests
+```bash
+hatch run test tests/test_image.py        # Single file
+hatch run test tests/test_image.py::test_name  # Single test
+hatch run test -k "image"                 # Tests matching pattern
+```
+
+## Code Style
+
+### Formatting
+- Line length: 120 characters
+- Use ruff for formatting and linting
+- Imports sorted with `banks` as first-party
+
+### Type Hints
+- All public functions should have type annotations
+- Use `from __future__ import annotations` for forward references
+- MyPy strict mode enforced
+
+### Conventions
+- SPDX license headers in all source files
+- Docstrings for public APIs
+- Relative imports banned (use absolute `from banks.x import y`)
+
+## Public API
+
+The main exports from `banks` package:
+```python
+from banks import Prompt, AsyncPrompt, ChatMessage, config, env
+```
+
+## Dependencies
+
+**Core (required)**:
+- `jinja2`: Core templating engine
+- `pydantic`: Type validation and serialization
+- `griffe`: Code introspection utilities
+- `platformdirs`: Cross-platform data directory handling
+- `filetype`: File type detection for multimodal content
+- `deprecated`: Deprecation decorators
+
+**Optional**:
+- `litellm`: Multi-provider LLM integration (`banks[all]`)
+- `redis`: Redis registry backend (`banks[all]`)
+- `simplemma`: Lemmatization filter (dev dependency)
+
+## CI/CD
+
+- **test.yml**: Runs tests on Python 3.10-3.14
+- **docs.yml**: Builds and deploys documentation
+- **release.yml**: Handles package releases
+
+## PR Guidelines
+
+Follow conventional commit prefixes for PR titles:
+- `fix:` - Bug fixes
+- `feat:` - New features
+- `chore:` - Maintenance
+- `docs:` - Documentation
+- `refactor:` - Code refactoring
+- `test:` - Test additions/changes

banks-2.4.0/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See [AGENTS.md](./AGENTS.md) for development guidance and project context.

{banks-2.2.0 → banks-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banks
-Version: 2.2.0
+Version: 2.4.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,11 +15,13 @@ 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
 Requires-Dist: deprecated
 Requires-Dist: eval-type-backport; python_version < '3.10'
+Requires-Dist: filetype>=1.2.0
 Requires-Dist: griffe
 Requires-Dist: jinja2
 Requires-Dist: platformdirs
@@ -125,11 +127,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.2.0 → banks-2.4.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.2.0 → banks-2.4.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",
 ]
@@ -29,6 +30,7 @@ dependencies = [
     "deprecated",
     "eval-type-backport;python_version<'3.10'",
     "platformdirs",
+    "filetype>=1.2.0",
 ]
 
 [project.optional-dependencies]
@@ -65,7 +67,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
@@ -77,6 +79,7 @@ lint = "pylint {args:src/banks}"
 typing = "mypy --install-types --non-interactive {args:src/banks}"
 all = ["check", "typing", "lint"]
 fmt = "ruff format {args}"
+fix = "ruff check --fix {args}"
 
 [tool.hatch.build.targets.wheel]
 only-include = ["src/banks", "src/templates"]
@@ -182,6 +185,7 @@ exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
 module = ["litellm.*", "simplemma.*", "deprecated.*"]
 ignore_missing_imports = true
 
+
 [tool.pylint]
 disable = [
     "line-too-long",
@@ -199,7 +203,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.2.0 → banks-2.4.0}/src/banks/__about__.py

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

{banks-2.2.0 → banks-2.4.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.2.0 → banks-2.4.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, xml
+from .filters import audio, cache_control, document, image, lemmatize, tool, video, xml
 
 
 def _add_extensions(_env):
@@ -38,6 +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.2.0 → banks-2.4.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.2.0 → banks-2.4.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.2.0 → banks-2.4.0}/src/banks/filters/__init__.py

@@ -3,9 +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", "xml")
+__all__ = ("cache_control", "image", "lemmatize", "tool", "audio", "video", "document", "xml")

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

@@ -0,0 +1,76 @@
+# 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
+
+import filetype  # type: ignore[import-untyped]
+
+from banks.types import AudioFormat, ContentBlock, InputAudio, resolve_binary
+
+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 _get_audio_format_from_bytes(data: bytes) -> AudioFormat:
+    """Extract audio format from bytes data using filetype library."""
+    kind = filetype.guess(data)
+    if kind is not None:
+        fmt = kind.extension
+        if fmt in ("mp3", "wav", "m4a", "webm", "ogg", "flac"):
+            return cast(AudioFormat, fmt)
+    # Default to mp3 if format cannot be determined
+    return "mp3"
+
+
+def audio(value: str | bytes) -> 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 isinstance(value, bytes):
+        audio_format = _get_audio_format_from_bytes(resolve_binary(value, as_base64=False))
+        input_audio = InputAudio.from_bytes(value, audio_format=audio_format)
+    elif _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>"