banks 2.1.1__tar.gz → 2.1.3__tar.gz

{banks-2.1.1 → banks-2.1.3}/.gitignore

@@ -82,25 +82,6 @@ target/
 profile_default/
 ipython_config.py
 
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
 #pdm.lock
@@ -156,3 +137,4 @@ cython_debug/
 .idea/
 .vscode/
 .zed/
+.claude/

banks-2.1.3/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) 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), and integrating with various LLM providers through LiteLLM.
+
+## Development Commands
+
+### Testing
+- Run tests: `hatch run test`
+- Run tests with coverage: `hatch run test-cov` 
+- Generate coverage report: `hatch run cov`
+- Run e2e tests specifically: `hatch run test tests/e2e/`
+
+### Linting and Type Checking
+- Format code: `hatch run lint:fmt`
+- 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
+- Use `uv` as the installer for faster dependency resolution
+- Python 3.9+ supported across multiple versions (3.9-3.13)
+
+## Architecture Overview
+
+### Core Components
+
+**Prompt Classes** (`src/banks/prompt.py`):
+- `BasePrompt`: Base class with common functionality for 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`)
+- `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) 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
+
+### 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 to base64-encoded image content blocks
+- `audio`: Convert audio files to base64-encoded audio 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
+
+### 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
+
+### Configuration
+
+**Config System** (`src/banks/config.py`):
+- Environment variable-based configuration with `BANKS_` prefix
+- `BANKS_ASYNC_ENABLED`: Enable async template rendering
+- `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 converted to base64 during filter application
+- 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 Strategy
+
+- 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
+
+## Key Dependencies
+
+- `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

banks-2.1.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+mpippi at gmail dot com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banks
-Version: 2.1.1
+Version: 2.1.3
 Summary: A prompt programming language
 Project-URL: Documentation, https://github.com/masci/banks#readme
 Project-URL: Issues, https://github.com/masci/banks/issues
@@ -123,8 +123,14 @@ print(p.chat_messages({"persona": "helpful assistant"}))
 
 # Output:
 # [
-#   ChatMessage(role='system', content='You are a helpful assistant.\n'),
-#   ChatMessage(role='user', content='Hello, how are you?\n')
+#   ChatMessage(role='system', content=[
+#      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='You are a helpful assistant.', 
+#                  image_url=None, input_audio=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)
+#   ], tool_call_id=None, name=None)
 # ]
 ```
 

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

@@ -92,8 +92,14 @@ print(p.chat_messages({"persona": "helpful assistant"}))
 
 # Output:
 # [
-#   ChatMessage(role='system', content='You are a helpful assistant.\n'),
-#   ChatMessage(role='user', content='Hello, how are you?\n')
+#   ChatMessage(role='system', content=[
+#      ContentBlock(type=<ContentBlockType.text: 'text'>, cache_control=None, text='You are a helpful assistant.', 
+#                  image_url=None, input_audio=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)
+#   ], tool_call_id=None, name=None)
 # ]
 ```
 

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

@@ -32,10 +32,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-all = [
-    "litellm",
-    "redis",
-]
+all = ["litellm", "redis"]
 
 [project.urls]
 Documentation = "https://github.com/masci/banks#readme"
@@ -71,7 +68,7 @@ docs = "mkdocs {args:build}"
 python = ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
 [tool.hatch.envs.lint]
-detached = false                                          # Normally the linting env can be detached, but mypy doesn't install all the stubs we need
+detached = false                                                              # Normally the linting env can be detached, but mypy doesn't install all the stubs we need
 dependencies = ["mypy>=1.0.0", "ruff>=0.0.243", "pylint", "redis", "litellm"]
 
 [tool.hatch.envs.lint.scripts]
@@ -147,6 +144,8 @@ ignore = [
     "PLR2004",
     # __all__ sorted
     "RUF022",
+    # Conditional imports
+    "PLC0415",
 ]
 
 [tool.ruff.lint.isort]
@@ -180,11 +179,7 @@ exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
 
 
 [[tool.mypy.overrides]]
-module = [
-    "litellm.*",
-    "simplemma.*",
-    "deprecated.*"
-]
+module = ["litellm.*", "simplemma.*", "deprecated.*"]
 ignore_missing_imports = true
 
 [tool.pylint]
@@ -202,11 +197,9 @@ max-args = 10
 
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "function"
-markers = [
-    "e2e",
-]
-filterwarnings =[
+markers = ["e2e"]
+filterwarnings = [
     # Dilence litellm warning coming from their Pydantic config.
     # This assumes our use of Pydantic is correct :)
-    "ignore:Support for class-based `config` is deprecated"
+    "ignore:Support for class-based `config` is deprecated",
 ]

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

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

{banks-2.1.1 → banks-2.1.3}/src/banks/extensions/chat.py

@@ -1,7 +1,6 @@
 # SPDX-FileCopyrightText: 2023-present Massimiliano Pippi <mpippi@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-import re
 
 from jinja2 import TemplateSyntaxError, nodes
 from jinja2.ext import Extension
@@ -9,7 +8,6 @@ from jinja2.ext import Extension
 from banks.types import chat_message_from_text
 
 SUPPORTED_TYPES = ("system", "user", "assistant")
-CONTENT_BLOCK_REGEX = re.compile(r"<content_block>((?s:.)*)<\/content_block>")
 
 
 class ChatExtension(Extension):
@@ -52,8 +50,8 @@ class ChatExtension(Extension):
             raise TemplateSyntaxError(error_msg, lineno)
 
         if attr_value.value not in SUPPORTED_TYPES:
-            types = ",".join(SUPPORTED_TYPES)
-            msg = f"Unknown role type '{attr_value}', use one of ({types})"
+            types = ", ".join(SUPPORTED_TYPES)
+            msg = f"Unknown role type '{attr_value.value}', use one of ({types})"
             raise TemplateSyntaxError(msg, lineno)
 
         # Pass the role name to the CallBlock node

{banks-2.1.1 → banks-2.1.3}/src/banks/registries/directory.py

@@ -27,7 +27,7 @@ DEFAULT_INDEX_NAME = "index.json"
 class PromptFile(PromptModel):
     """Model representing a prompt file stored on disk."""
 
-    path: Path = Field(exclude=True)
+    path: Path | None = Field(default=None, exclude=True)
 
     @classmethod
     def from_prompt_path(cls: type[Self], prompt: Prompt, path: Path) -> Self:
@@ -101,7 +101,7 @@ class DirectoryPromptRegistry:
         """
         version = version or DEFAULT_VERSION
         for pf in self._index.files:
-            if pf.name == name and pf.version == version and pf.path.exists():
+            if pf.name == name and pf.version == version and pf.path and pf.path.exists():
                 return Prompt(**pf.model_dump())
         raise PromptNotFoundError
 
@@ -135,6 +135,10 @@ class DirectoryPromptRegistry:
     def _load(self):
         """Load the prompt index from disk."""
         self._index = PromptFileIndex.model_validate_json(self._index_path.read_text())
+        # Reconstruct the file paths since they're excluded from serialization
+        for pf in self._index.files:
+            if pf.path is None:
+                pf.path = self._path / f"{pf.name}.{pf.version}.jinja"
 
     def _save(self):
         """Save the prompt index to disk."""

{banks-2.1.1 → banks-2.1.3}/src/banks/types.py

@@ -16,7 +16,7 @@ from typing_extensions import Self
 from .utils import parse_params_from_docstring, python_type_to_jsonschema
 
 # pylint: disable=invalid-name
-CONTENT_BLOCK_REGEX = re.compile(r"(<content_block>\{.*?\}<\/content_block>)|([^<](?:(?!<content_block>).)*)")
+CONTENT_BLOCK_REGEX = re.compile(r"(<content_block>\{.*?\}<\/content_block>)|([^<](?:(?!<content_block>)[\s\S])*)")
 
 
 class ContentBlockType(str, Enum):

{banks-2.1.1 → banks-2.1.3}/tests/conftest.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 import pytest
 import redis
 
@@ -19,3 +21,9 @@ def skip_by_redis(request):
     if request.node.get_closest_marker("redis"):
         if not is_redis_available():
             pytest.skip("Redis is not available")
+
+
+@pytest.fixture
+def data_path() -> Path:
+    here = Path(__file__).parent
+    return here / "data"

banks-2.1.3/tests/test_chat.py

@@ -0,0 +1,82 @@
+from typing import cast
+
+import pytest
+from jinja2 import TemplateSyntaxError
+
+from banks import Prompt
+from banks.types import ContentBlock
+
+
+def test_wrong_tag():
+    with pytest.raises(TemplateSyntaxError):
+        Prompt("{% chat %}{% endchat %}")
+
+
+def test_wrong_tag_params():
+    with pytest.raises(TemplateSyntaxError):
+        Prompt('{% chat foo="bar" %}{% endchat %}')
+
+
+def test_wrong_role_type():
+    with pytest.raises(TemplateSyntaxError):
+        Prompt('{% chat role="does not exist" %}{% endchat %}')
+
+
+def test_blocks():
+    p = Prompt('{% chat role="user" %}Tell me what you see: {{ picture | image }}{% endchat %}')
+    messages = p.chat_messages({"picture": "http://foo.bar"})
+    assert len(messages) == 1
+    content = messages[0].content
+    assert len(content) == 2
+    assert content[0].type == "text"  # type: ignore
+    assert content[1].type == "image_url"  # type: ignore
+
+
+def test_blocks_newlines():
+    p = Prompt("""{% chat role="system" %}
+Some instructions:
+
+1. Do this.
+2. Then this.
+3. Finally, that.
+{% endchat %}""")
+    messages = p.chat_messages()
+    assert len(messages) == 1
+    assert len(messages[0].content) == 1
+
+
+def test_blocks_complex(data_path):
+    p = Prompt("""
+{% chat role="system" %}
+Given a list of images and text from each image, please answer the question to the best of your ability.
+{% endchat %}
+
+{% chat role="user" %}
+{% for image_path, text in images_and_texts %}
+Here is some text: {{ text }}
+And here is an image:
+{{ image_path | image }}
+{% endfor %}
+{% endchat %}
+    """)
+
+    messages = p.chat_messages(
+        {
+            "images_and_texts": [
+                (str(data_path / "1x1.png"), "This is the first page of the document"),
+                (str(data_path / "1x1.png"), "This is the second page of the document"),
+            ]
+        }
+    )
+    assert len(messages) == 2
+
+    blocks = cast(list[ContentBlock], messages[0].content)
+    assert len(blocks) == 1
+    assert blocks[0].type == "text"
+
+    blocks = cast(list[ContentBlock], messages[1].content)
+    assert len(blocks) == 4
+    assert blocks[0].type == "text"
+    assert blocks[1].type == "image_url"
+    assert blocks[2].type == "text"
+    assert blocks[3].type == "image_url"

banks-2.1.1/tests/test_chat.py

@@ -1,29 +0,0 @@
-import pytest
-from jinja2 import TemplateSyntaxError
-
-from banks import Prompt
-
-
-def test_wrong_tag():
-    with pytest.raises(TemplateSyntaxError):
-        Prompt("{% chat %}{% endchat %}")
-
-
-def test_wrong_tag_params():
-    with pytest.raises(TemplateSyntaxError):
-        Prompt('{% chat foo="bar" %}{% endchat %}')
-
-
-def test_wrong_role_type():
-    with pytest.raises(TemplateSyntaxError):
-        Prompt('{% chat role="does not exist" %}{% endchat %}')
-
-
-def test_blocks():
-    p = Prompt('{% chat role="user" %}Tell me what you see: {{ picture | image }}{% endchat %}')
-    messages = p.chat_messages({"picture": "http://foo.bar"})
-    assert len(messages) == 1
-    content = messages[0].content
-    assert len(content) == 2
-    assert content[0].type == "text"  # type: ignore
-    assert content[1].type == "image_url"  # type: ignore