banks 2.3.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.3.0/CLAUDE.md → banks-2.4.0/AGENTS.md

@@ -1,21 +1,33 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+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` 
+- Run tests with coverage: `hatch run test-cov`
 - Generate coverage report: `hatch run cov`
-- Run e2e tests specifically: `hatch run test tests/e2e/`
+- 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`
@@ -27,17 +39,17 @@ 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.10+ supported across multiple versions (3.10-3.14)
+- 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 common functionality for template rendering, metadata, versioning, and caching
+- `BasePrompt`: Base class with template rendering, metadata, versioning, and caching
 - `Prompt`: Synchronous prompt rendering with `text()` and `chat_messages()` methods
-- `AsyncPrompt`: Asynchronous version for use within asyncio loops (requires `BANKS_ASYNC_ENABLED=true`)
+- `AsyncPrompt`: Asynchronous version (requires `BANKS_ASYNC_ENABLED=true`)
 - `PromptRegistry`: Protocol interface for prompt storage backends
 
 **Type System** (`src/banks/types.py`):
@@ -51,13 +63,21 @@ Banks is a Python prompt programming language and templating system for LLM appl
 - 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 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
@@ -65,39 +85,49 @@ Banks is a Python prompt programming language and templating system for LLM appl
 ### Filters System
 
 **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  
+- `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  
+- `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
+- `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  
+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
 
@@ -106,23 +136,83 @@ Banks is a Python prompt programming language and templating system for LLM appl
 - Docstring parsing for parameter descriptions
 - Type annotations converted to JSON Schema
 
-### Async Support Architecture  
+### 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 Strategy
+## 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
 
-- Unit tests for individual components in `tests/`
-- E2e tests requiring API keys in `tests/e2e/` (marked with `@pytest.mark.e2e`)
-- Template examples in `tests/templates/` for integration testing
-- Coverage excludes async-specific code paths and deprecated modules
+The main exports from `banks` package:
+```python
+from banks import Prompt, AsyncPrompt, ChatMessage, config, env
+```
 
-## Key Dependencies
+## Dependencies
 
+**Core (required)**:
 - `jinja2`: Core templating engine
 - `pydantic`: Type validation and serialization
-- `litellm`: Multi-provider LLM integration (optional)
-- `redis`: Redis registry backend (optional)
 - `griffe`: Code introspection utilities
-- `platformdirs`: Cross-platform data directory handling
+- `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.3.0 → banks-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banks
-Version: 2.3.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
@@ -21,6 +21,7 @@ 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

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

@@ -30,6 +30,7 @@ dependencies = [
     "deprecated",
     "eval-type-backport;python_version<'3.10'",
     "platformdirs",
+    "filetype>=1.2.0",
 ]
 
 [project.optional-dependencies]
@@ -78,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"]
@@ -183,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",

{banks-2.3.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.3.0"
+__version__ = "2.4.0"

{banks-2.3.0 → banks-2.4.0}/src/banks/filters/audio.py

@@ -6,7 +6,9 @@ from pathlib import Path
 from typing import cast
 from urllib.parse import urlparse
 
-from banks.types import AudioFormat, ContentBlock, InputAudio
+import filetype  # type: ignore[import-untyped]
+
+from banks.types import AudioFormat, ContentBlock, InputAudio, resolve_binary
 
 BASE64_AUDIO_REGEX = re.compile(r"audio\/.*;base64,.*")
 
@@ -38,7 +40,18 @@ def _get_audio_format_from_url(url: str) -> AudioFormat:
     return "mp3"
 
 
-def audio(value: str) -> str:
+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.
@@ -51,7 +64,10 @@ def audio(value: str) -> str:
         {{ "https://example.com/audio.mp3" | audio }}
         ```
     """
-    if _is_url(value):
+    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:

{banks-2.3.0 → banks-2.4.0}/src/banks/filters/document.py

@@ -1,12 +1,15 @@
 # SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
 #
 # SPDX-License-Identifier: MIT
+import mimetypes
 import re
 from pathlib import Path
 from typing import cast
 from urllib.parse import urlparse
 
-from banks.types import ContentBlock, DocumentFormat, InputDocument
+import filetype  # type: ignore[import-untyped]
+
+from banks.types import ContentBlock, DocumentFormat, InputDocument, resolve_binary
 
 BASE64_DOCUMENT_REGEX = re.compile(r"(text|application)\/.*;base64,.*")
 
@@ -36,7 +39,7 @@ def _get_document_format_from_url(url: str) -> DocumentFormat:
     # text/css
     # text/plain
     # text/xml
-    # text/scv
+    # text/csv
     # text/rtf
     # text/javascript
     # application/json
@@ -68,13 +71,46 @@ def _get_document_format_from_url(url: str) -> DocumentFormat:
         "javascript",
         "json",
     ):
+        # Because Claude only supports pdf and text, and Gemini only supports a small subset of text formats,
+        # we can default to 'txt' for any text-based format that is not pdf. This allows the data to be sent to the llm
+        # in an acceptable format, but the LLM should still be able to understand the content: e.g., html, markdown,
+        # xml, etc.
         if path.endswith(f".{fmt}"):
+            if fmt == "pdf":
+                return cast(DocumentFormat, "pdf")
+            return "txt"
+    mime = mimetypes.guess_type(path)[0]
+    if mime is not None and mime.startswith("text/"):
+        return "txt"
+    # With urls, the likelihood seems sufficiently high that it's probably a pdf if not otherwise indicated
+    if mime is None:
+        return "pdf"
+    # Document type indicated to be other than pdf or text type
+    raise ValueError("Unsupported document format: " + path)
+
+
+def _get_document_format_from_bytes(data: bytes) -> DocumentFormat:
+    """Extract document format from bytes data using filetype library."""
+    # First check for pdf (only non text based format) and RTF formats (can be detected by file header)
+    kind = filetype.guess(data)
+    if kind is not None:
+        fmt = kind.extension
+        if fmt == "pdf":
             return cast(DocumentFormat, fmt)
-    # Default to pdf if format cannot be determined
-    return "pdf"
+
+    # filetype is good at detecting binary formats, but not text-based ones.
+    # So, this is a good indicator that it's text-based.
+    # Because Claude only supports pdf and text, and Gemini only supports a small subset of text formats,
+    # we can default to 'txt' for any text-based format that is not pdf. This allows the data to be sent to the llm in
+    # an acceptable format, but the LLM should still be able to understand the content: e.g., html, markdown, xml, etc.
+    # If detecting text types should become desirable, I recommend using something like Google magicka
+    if kind is None or kind.extension == "rtf":
+        return "txt"
+    # There are many common document types (like word, excel, powerpoint, etc.) that are not supported.
+    raise ValueError("Unsupported document format: " + kind.extension)
 
 
-def document(value: str) -> str:
+def document(value: str | bytes) -> 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.
@@ -87,7 +123,10 @@ def document(value: str) -> str:
         {{ "https://example.com/document.pdf" | document }}
         ```
     """
-    if _is_url(value):
+    if isinstance(value, bytes):
+        document_format = _get_document_format_from_bytes(resolve_binary(value, as_base64=False))
+        input_document = InputDocument.from_bytes(value, document_format=document_format)
+    elif _is_url(value):
         document_format = _get_document_format_from_url(value)
         input_document = InputDocument.from_url(value, document_format)
     else:

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

@@ -22,7 +22,7 @@ def _is_url(string: str) -> bool:
     return True
 
 
-def image(value: str) -> str:
+def image(value: str | bytes) -> str:
     """Wrap the filtered value into a ContentBlock of type image.
 
     The resulting ChatMessage will have the field `content` populated with a list of ContentBlock objects.
@@ -38,7 +38,9 @@ def image(value: str) -> str:
         this filter marks the content to cache by surrounding it with `<content_block>` and
         `</content_block>`, so it's only useful when used within a `{% chat %}` block.
     """
-    if _is_url(value):
+    if isinstance(value, bytes):
+        image_url = ImageUrl.from_bytes(bytes_str=value)
+    elif _is_url(value):
         image_url = ImageUrl(url=value)
     else:
         image_url = ImageUrl.from_path(Path(value))

{banks-2.3.0 → banks-2.4.0}/src/banks/filters/video.py

@@ -6,11 +6,39 @@ from pathlib import Path
 from typing import cast
 from urllib.parse import urlparse
 
-from banks.types import ContentBlock, InputVideo, VideoFormat
+import filetype  # type: ignore[import-untyped]
+from filetype.types.video import IsoBmff  # type: ignore[import-untyped]
+
+from banks.types import ContentBlock, InputVideo, VideoFormat, resolve_binary
 
 BASE64_VIDEO_REGEX = re.compile(r"video\/.*;base64,.*")
 
 
+class M3gp(IsoBmff):
+    """
+    Implements the 3gp video type matcher.
+
+    The type matcher in the filetype lib does not work correctly for 3gp files,
+    so implement our own here.
+    """
+
+    MIME = "video/3gpp"
+    EXTENSION = "3gp"
+
+    def __init__(self):
+        super().__init__(mime=M3gp.MIME, extension=M3gp.EXTENSION)
+
+    def match(self, buf):
+        if not self._is_isobmff(buf):
+            return False
+
+        major_brand, _, compatible_brands = self._get_ftyp(buf)
+        for brand in compatible_brands:
+            if brand in ["3gp4", "3gp5", "3gpp"]:
+                return True
+        return major_brand in ["3gp4", "3gp5", "3gpp"]
+
+
 def _is_url(string: str) -> bool:
     """Check if a string is a URL."""
     result = urlparse(string)
@@ -40,7 +68,22 @@ def _get_video_format_from_url(url: str) -> VideoFormat:
     return "mp4"
 
 
-def video(value: str) -> str:
+def _get_video_format_from_bytes(data: bytes) -> VideoFormat:
+    """Extract video format from bytes data using filetype library."""
+    m3gp = M3gp()
+    if m3gp not in filetype.types:
+        filetype.add_type(m3gp)
+
+    kind = filetype.guess(data)
+    if kind is not None:
+        fmt = kind.extension
+        if fmt in ("mp4", "mpg", "mov", "avi", "flv", "webm", "wmv", "3gp"):
+            return cast(VideoFormat, fmt)
+    # Default to mp4 if format cannot be determined
+    return "mp4"
+
+
+def video(value: str | bytes) -> 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.
@@ -53,7 +96,10 @@ def video(value: str) -> str:
         {{ "https://example.com/video.mp4" | video }}
         ```
     """
-    if _is_url(value):
+    if isinstance(value, bytes):
+        video_format = _get_video_format_from_bytes(resolve_binary(value, as_base64=False))
+        input_video = InputVideo.from_bytes(value, video_format=video_format)
+    elif _is_url(value):
         video_format = _get_video_format_from_url(value)
         input_video = InputVideo.from_url(value, video_format)
     else: