banks 2.1.2__tar.gz → 2.1.3__tar.gz

{banks-2.1.2 → 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.2 → banks-2.1.3}/PKG-INFO

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

{banks-2.1.2 → 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.2 → 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.2"
+__version__ = "2.1.3"

{banks-2.1.2 → 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."""