ai-prompter 0.1.0__py3-none-any.whl

ai_prompter/__init__.py

@@ -0,0 +1,155 @@
+"""
+A prompt management module using Jinja to generate complex prompts with simple templates.
+"""
+
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, Optional, Union
+
+from jinja2 import Environment, FileSystemLoader, Template
+from pydantic import BaseModel
+
+prompt_path_default = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "prompts"
+)
+prompt_path_custom = os.getenv("PROMPT_PATH")
+
+env_default = Environment(loader=FileSystemLoader(prompt_path_default))
+
+
+@dataclass
+class Prompter:
+    """
+    A class for managing and rendering prompt templates.
+
+    Attributes:
+        prompt_template (str, optional): The name of the prompt template file.
+        prompt_variation (str, optional): The variation of the prompt template.
+        prompt_text (str, optional): The raw prompt text.
+        template (Union[str, Template], optional): The Jinja2 template object.
+    """
+
+    prompt_template: Optional[str] = None
+    prompt_variation: Optional[str] = "default"
+    prompt_text: Optional[str] = None
+    template: Optional[Union[str, Template]] = None
+    parser: Optional[Any] = None
+
+    def __init__(self, prompt_template=None, prompt_text=None, parser=None):
+        """
+        Initialize the Prompter with either a template file or raw text.
+
+        Args:
+            prompt_template (str, optional): The name of the prompt template file.
+            prompt_text (str, optional): The raw prompt text.
+        """
+        self.prompt_template = prompt_template
+        self.prompt_text = prompt_text
+        self.parser = parser
+        self.setup()
+
+    def setup(self):
+        """
+        Set up the Jinja2 template based on the provided template file or text.
+        Raises:
+            ValueError: If neither prompt_template nor prompt_text is provided, or if template name is empty.
+        """
+        if self.prompt_template is not None:
+            if not self.prompt_template:
+                raise ValueError("Template name cannot be empty")
+            # attempt to load from custom path at runtime
+            custom_path = os.getenv("PROMPT_PATH")
+            if custom_path and os.path.exists(custom_path):
+                try:
+                    env = Environment(loader=FileSystemLoader(custom_path))
+                    self.template = env.get_template(f"{self.prompt_template}.jinja")
+                    return
+                except Exception:
+                    pass
+            # fallback to default path
+            try:
+                env = Environment(loader=FileSystemLoader(prompt_path_default))
+                self.template = env.get_template(f"{self.prompt_template}.jinja")
+            except Exception as e:
+                raise ValueError(f"Template {self.prompt_template} not found in default folder: {e}")
+        elif self.prompt_text is not None:
+            self.template = Template(self.prompt_text)
+        else:
+            raise ValueError("Prompter must have a prompt_template or prompt_text")
+
+        # Removed assertion as it's redundant with the checks above
+        # assert self.prompt_template or self.prompt_text, "Prompt is required"
+
+    def to_langchain(self):
+        # only file-based templates supported for LangChain
+        if self.prompt_text is not None:
+            raise ImportError(
+                "langchain-core integration only supports file-based templates; install with `pip install .[langchain]`"
+            )
+        try:
+            from langchain_core.prompts import ChatPromptTemplate
+        except ImportError:
+            raise ImportError(
+                "langchain-core is required for to_langchain; install with `pip install .[langchain]`"
+            )
+        if isinstance(self.template, str):
+            template_text = self.template
+        elif isinstance(self.template, Template):
+            # raw Jinja2 template object
+            template_text = self.prompt_text
+        else:
+            # file-based template
+            prompt_dir = (
+                prompt_path_custom
+                if prompt_path_custom and os.path.exists(prompt_path_custom)
+                else prompt_path_default
+            )
+            template_file = os.path.join(prompt_dir, f"{self.prompt_template}.jinja")
+            with open(template_file, "r") as f:
+                template_text = f.read()
+        return ChatPromptTemplate.from_template(template_text, template_format="jinja2")
+
+    @classmethod
+    def from_text(cls, text: str):
+        """
+        Create a Prompter instance from raw text, which can contain Jinja code.
+
+        Args:
+            text (str): The raw prompt text.
+
+        Returns:
+            Prompter: A new Prompter instance.
+        """
+
+        return cls(prompt_text=text)
+
+    def render(self, data: Optional[Union[Dict, BaseModel]] = None) -> str:
+        """
+        Render the prompt template with the given data.
+
+        Args:
+            data (Union[Dict, BaseModel]): The data to be used in rendering the template.
+                Can be either a dictionary or a Pydantic BaseModel.
+
+        Returns:
+            str: The rendered prompt text.
+
+        Raises:
+            AssertionError: If the template is not defined or not a Jinja2 Template.
+        """
+        if isinstance(data, BaseModel):
+            data_dict = data.model_dump()
+        elif isinstance(data, dict):
+            data_dict = data
+        else:
+            data_dict = {}
+        render_data = dict(data_dict)
+        render_data["current_time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        if self.parser:
+            render_data["format_instructions"] = self.parser.get_format_instructions()
+        assert self.template, "Prompter template is not defined"
+        assert isinstance(
+            self.template, Template
+        ), "Prompter template is not a Jinja2 Template"
+        return self.template.render(render_data)

ai_prompter-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: ai-prompter
+Version: 0.1.0
+Summary: A prompt management library using Jinja2 templates to build complex prompts easily.
+Author-email: LUIS NOVO <lfnovo@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10.6
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pip>=25.0.1
+Requires-Dist: pydantic>=2.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AI Prompter
+
+A prompt management library using Jinja2 templates to build complex prompts easily. Supports raw text or file-based templates and integrates with LangChain.
+
+## Features
+
+- Define prompts as Jinja templates.
+- Load default templates from `src/ai_prompter/prompts`.
+- Override templates via `PROMPT_PATH` environment variable.
+- Render prompts with arbitrary data or Pydantic models.
+- Export to LangChain `ChatPromptTemplate`.
+
+## Installation
+
+1. (Optional) Create and activate a virtual environment:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+2. Install the package:
+   ```bash
+   pip install .
+   ```
+### Extras
+
+To enable LangChain integration:
+
+```bash
+pip install .[langchain]
+# or
+uv add langchain_core
+```
+
+## Configuration
+
+Configure a custom template path by creating a `.env` file in the project root:
+
+```dotenv
+PROMPT_PATH=path/to/custom/templates
+```
+
+## Usage
+
+### Raw text template
+
+```python
+from ai_prompter import Prompter
+
+template = """Write an article about {{ topic }}."""
+prompter = Prompter(prompt_text=template)
+prompt = prompter.render({"topic": "AI"})
+print(prompt)  # Write an article about AI.
+```
+
+### Using File-based Templates
+
+You can store your templates in files and reference them by name (without the `.jinja` extension). The library looks for templates in the `prompts` directory by default, or you can set a custom directory with the `PROMPT_PATH` environment variable.
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_template="greet")
+prompt = prompter.render({"who": "Tester"})
+print(prompt)  # GREET Tester
+```
+
+### Including Other Templates
+
+You can include other template files within a template using Jinja2's `{% include %}` directive. This allows you to build modular templates.
+
+```jinja
+# outer.jinja
+This is the outer file
+
+{% include 'inner.jinja' %}
+
+This is the end of the outer file
+```
+
+```jinja
+# inner.jinja
+This is the inner file
+
+{% if type == 'a' %}
+    You selected A
+{% else %}
+    You didn't select A
+{% endif %}
+```
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_template="outer")
+prompt = prompter.render(dict(type="a"))
+print(prompt)
+# This is the outer file
+# 
+# This is the inner file
+# 
+#     You selected A
+# 
+# 
+# This is the end of the outer file
+```
+
+### Using Variables
+
+Templates can use variables that you pass in through the `render()` method. You can use Jinja2 filters and conditionals to control the output based on your data.
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_text="Hello {{name|default('Guest')}}!")
+prompt = prompter.render()  # No data provided, uses default
+print(prompt)  # Hello Guest!
+prompt = prompter.render({"name": "Alice"})  # Data provided
+print(prompt)  # Hello Alice!
+```
+
+The library also automatically provides a `current_time` variable with the current timestamp in format "YYYY-MM-DD HH:MM:SS".
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_text="Current time: {{current_time}}")
+prompt = prompter.render()
+print(prompt)  # Current time: 2025-04-19 23:28:00
+```
+
+### File-based template
+
+Place a Jinja file (e.g., `article.jinja`) in the default prompts directory (`src/ai_prompter/prompts`) or your custom path:
+
+```jinja
+Write an article about {{ topic }}.
+```
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_template="article")
+prompt = prompter.render({"topic": "AI"})
+print(prompt)
+```
+
+### LangChain integration
+
+```python
+from ai_prompter import Prompter
+
+prompter = Prompter(prompt_template="article")
+lc_template = prompter.to_langchain()
+# use lc_template in LangChain chains
+```
+
+### Jupyter Notebook
+
+See `notebooks/prompter_usage.ipynb` for interactive examples.
+
+## Project Structure
+
+```
+ai-prompter/
+├── src/ai_prompter
+│   ├── __init__.py
+│   └── prompts/
+│       └── *.jinja
+├── notebooks/
+│   ├── prompter_usage.ipynb
+│   └── prompts/
+├── pyproject.toml
+├── README.md
+└── .env (optional)
+```
+
+## Testing
+
+Run tests with:
+
+```bash
+uv run pytest -v
+```
+
+## Contributing
+
+Contributions welcome! Please open issues or PRs.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

ai_prompter-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+ai_prompter/__init__.py,sha256=4Zzy7drJRTmQZGJCEcqnf1-RkvDvZiLIYXLDeyFXGJw,5913
+ai_prompter-0.1.0.dist-info/METADATA,sha256=6siPIYPmficMeNOXkSzXk4-GjzTacIhaJjF2BRc7WUM,4757
+ai_prompter-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ai_prompter-0.1.0.dist-info/licenses/LICENSE,sha256=cS0_fa_8BoP0PvVG8D19pn_HDJrG96hd4PyEm9nkRo8,1066
+ai_prompter-0.1.0.dist-info/RECORD,,

ai_prompter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_prompter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luis Novo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.