ai-prompter 0.2.2__tar.gz → 0.3.0__tar.gz

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-prompter
-Version: 0.2.2
+Version: 0.3.0
 Summary: A prompt management library using Jinja2 templates to build complex prompts easily.
 Author-email: LUIS NOVO <lfnovo@gmail.com>
 License: MIT
@@ -22,8 +22,10 @@ A prompt management library using Jinja2 templates to build complex prompts easi
 - Define prompts as Jinja templates.
 - Load default templates from `src/ai_prompter/prompts`.
 - Override templates via `PROMPTS_PATH` environment variable.
+- Automatic project root detection for prompt templates.
 - Render prompts with arbitrary data or Pydantic models.
 - Export to LangChain `ChatPromptTemplate`.
+- Automatic output parser integration for structured outputs.
 
 ## Installation
 
@@ -85,32 +87,70 @@ Set the `PROMPTS_PATH` environment variable to point to your custom prompts dire
 export PROMPTS_PATH=/path/to/your/prompts
 ```
 
-The `Prompter` class will check this path if no custom directory is provided in the constructor. If not set, it will also look in the current working directory and `~/ai-prompter/` as fallback options before using the default package prompts.
+You can specify multiple directories separated by `:` (colon):
 
-### Raw text template
+```bash
+export PROMPTS_PATH=/path/to/templates1:/path/to/templates2
+```
 
-```python
-from ai_prompter import Prompter
+### Template Search Order
 
-template = """Write an article about {{ topic }}."""
-prompter = Prompter(template_text=template)
-prompt = prompter.render({"topic": "AI"})
-print(prompt)  # Write an article about AI.
+The `Prompter` class searches for templates in the following locations (in order of priority):
+
+1. **Custom directory** - If you provide `prompt_dir` parameter when initializing Prompter
+2. **Environment variable paths** - Directories specified in `PROMPTS_PATH` (colon-separated)
+3. **Current directory prompts** - `./prompts` subfolder in your current working directory
+4. **Project root prompts** - Automatically detects your Python project root (by looking for `pyproject.toml`, `setup.py`, `setup.cfg`, or `.git`) and checks for a `prompts` folder there
+5. **Home directory** - `~/ai-prompter` folder
+6. **Package defaults** - Built-in templates at `src/ai_prompter/prompts`
+
+This allows you to organize your project with prompts at the root level, regardless of your package structure:
+```
+my-project/
+├── prompts/           # <- Templates here will be found automatically
+│   └── my_template.jinja
+├── src/
+│   └── my_package/
+│       └── main.py
+└── pyproject.toml
 ```
 
 ### 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 `PROMPTS_PATH` environment variable. You can specify multiple directories separated by `:` (colon), and the library will search through them in order until a matching template is found.
+You can store your templates in files and reference them by name (without the `.jinja` extension). The library will search through all configured paths (see Template Search Order above) until a matching template is found.
 
 ```python
 from ai_prompter import Prompter
 
+# Will search for 'greet.jinja' in all configured paths
+prompter = Prompter(prompt_template="greet")
+result = prompter.render({"name": "World"})
+print(result)  # Output depends on the content of greet.jinja
+```
+
+You can also specify multiple search paths via environment variable:
+
+```python
+import os
+from ai_prompter import Prompter
+
 # Set multiple search paths
 os.environ["PROMPTS_PATH"] = "/path/to/templates1:/path/to/templates2"
 
 prompter = Prompter(prompt_template="greet")
 result = prompter.render({"name": "World"})
-print(result)  # Output depends on the content of greet.jinja in the first found path
+print(result)  # Uses greet.jinja from the first path where it's found
+```
+
+### Raw text template
+
+```python
+from ai_prompter import Prompter
+
+template = """Write an article about {{ topic }}."""
+prompter = Prompter(template_text=template)
+prompt = prompter.render({"topic": "AI"})
+print(prompt)  # Write an article about AI.
 ```
 
 ### Using Raw Text Templates
@@ -149,6 +189,61 @@ lc_file_prompt = file_prompter.to_langchain()
 
 **Note**: LangChain integration requires the `langchain-core` package. Install it with `pip install .[langchain]`.
 
+### Using Output Parsers
+
+The Prompter class supports LangChain output parsers to automatically inject formatting instructions into your prompts. When you provide a parser, it will call the parser's `get_format_instructions()` method and make the result available as `{{ format_instructions }}` in your template.
+
+```python
+from ai_prompter import Prompter
+from langchain.output_parsers import PydanticOutputParser
+from pydantic import BaseModel, Field
+
+# Define your output model
+class Article(BaseModel):
+    title: str = Field(description="Article title")
+    summary: str = Field(description="Brief summary")
+    tags: list[str] = Field(description="Relevant tags")
+
+# Create a parser
+parser = PydanticOutputParser(pydantic_object=Article)
+
+# Create a prompter with the parser
+prompter = Prompter(
+    template_text="""Write an article about {{ topic }}.
+
+{{ format_instructions }}""",
+    parser=parser
+)
+
+# Render the prompt - format instructions are automatically included
+prompt = prompter.render({"topic": "AI Safety"})
+print(prompt)
+# Output will include the topic AND the parser's format instructions
+```
+
+This works with file-based templates too:
+
+```jinja
+# article_structured.jinja
+Write an article about {{ topic }}.
+
+Please format your response according to these instructions:
+{{ format_instructions }}
+```
+
+```python
+prompter = Prompter(
+    prompt_template="article_structured",
+    parser=parser
+)
+```
+
+The parser integration supports any LangChain output parser that implements `get_format_instructions()`, including:
+- `PydanticOutputParser` - For structured Pydantic model outputs
+- `OutputFixingParser` - For fixing malformed outputs
+- `RetryOutputParser` - For retrying failed parsing attempts
+- `StructuredOutputParser` - For dictionary-based structured outputs
+
 ### Including Other Templates
 
 You can include other template files within a template using Jinja2's `{% include %}` directive. This allows you to build modular templates.

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/README.md

@@ -7,8 +7,10 @@ A prompt management library using Jinja2 templates to build complex prompts easi
 - Define prompts as Jinja templates.
 - Load default templates from `src/ai_prompter/prompts`.
 - Override templates via `PROMPTS_PATH` environment variable.
+- Automatic project root detection for prompt templates.
 - Render prompts with arbitrary data or Pydantic models.
 - Export to LangChain `ChatPromptTemplate`.
+- Automatic output parser integration for structured outputs.
 
 ## Installation
 
@@ -70,32 +72,70 @@ Set the `PROMPTS_PATH` environment variable to point to your custom prompts dire
 export PROMPTS_PATH=/path/to/your/prompts
 ```
 
-The `Prompter` class will check this path if no custom directory is provided in the constructor. If not set, it will also look in the current working directory and `~/ai-prompter/` as fallback options before using the default package prompts.
+You can specify multiple directories separated by `:` (colon):
 
-### Raw text template
+```bash
+export PROMPTS_PATH=/path/to/templates1:/path/to/templates2
+```
 
-```python
-from ai_prompter import Prompter
+### Template Search Order
 
-template = """Write an article about {{ topic }}."""
-prompter = Prompter(template_text=template)
-prompt = prompter.render({"topic": "AI"})
-print(prompt)  # Write an article about AI.
+The `Prompter` class searches for templates in the following locations (in order of priority):
+
+1. **Custom directory** - If you provide `prompt_dir` parameter when initializing Prompter
+2. **Environment variable paths** - Directories specified in `PROMPTS_PATH` (colon-separated)
+3. **Current directory prompts** - `./prompts` subfolder in your current working directory
+4. **Project root prompts** - Automatically detects your Python project root (by looking for `pyproject.toml`, `setup.py`, `setup.cfg`, or `.git`) and checks for a `prompts` folder there
+5. **Home directory** - `~/ai-prompter` folder
+6. **Package defaults** - Built-in templates at `src/ai_prompter/prompts`
+
+This allows you to organize your project with prompts at the root level, regardless of your package structure:
+```
+my-project/
+├── prompts/           # <- Templates here will be found automatically
+│   └── my_template.jinja
+├── src/
+│   └── my_package/
+│       └── main.py
+└── pyproject.toml
 ```
 
 ### 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 `PROMPTS_PATH` environment variable. You can specify multiple directories separated by `:` (colon), and the library will search through them in order until a matching template is found.
+You can store your templates in files and reference them by name (without the `.jinja` extension). The library will search through all configured paths (see Template Search Order above) until a matching template is found.
 
 ```python
 from ai_prompter import Prompter
 
+# Will search for 'greet.jinja' in all configured paths
+prompter = Prompter(prompt_template="greet")
+result = prompter.render({"name": "World"})
+print(result)  # Output depends on the content of greet.jinja
+```
+
+You can also specify multiple search paths via environment variable:
+
+```python
+import os
+from ai_prompter import Prompter
+
 # Set multiple search paths
 os.environ["PROMPTS_PATH"] = "/path/to/templates1:/path/to/templates2"
 
 prompter = Prompter(prompt_template="greet")
 result = prompter.render({"name": "World"})
-print(result)  # Output depends on the content of greet.jinja in the first found path
+print(result)  # Uses greet.jinja from the first path where it's found
+```
+
+### Raw text template
+
+```python
+from ai_prompter import Prompter
+
+template = """Write an article about {{ topic }}."""
+prompter = Prompter(template_text=template)
+prompt = prompter.render({"topic": "AI"})
+print(prompt)  # Write an article about AI.
 ```
 
 ### Using Raw Text Templates
@@ -134,6 +174,61 @@ lc_file_prompt = file_prompter.to_langchain()
 
 **Note**: LangChain integration requires the `langchain-core` package. Install it with `pip install .[langchain]`.
 
+### Using Output Parsers
+
+The Prompter class supports LangChain output parsers to automatically inject formatting instructions into your prompts. When you provide a parser, it will call the parser's `get_format_instructions()` method and make the result available as `{{ format_instructions }}` in your template.
+
+```python
+from ai_prompter import Prompter
+from langchain.output_parsers import PydanticOutputParser
+from pydantic import BaseModel, Field
+
+# Define your output model
+class Article(BaseModel):
+    title: str = Field(description="Article title")
+    summary: str = Field(description="Brief summary")
+    tags: list[str] = Field(description="Relevant tags")
+
+# Create a parser
+parser = PydanticOutputParser(pydantic_object=Article)
+
+# Create a prompter with the parser
+prompter = Prompter(
+    template_text="""Write an article about {{ topic }}.
+
+{{ format_instructions }}""",
+    parser=parser
+)
+
+# Render the prompt - format instructions are automatically included
+prompt = prompter.render({"topic": "AI Safety"})
+print(prompt)
+# Output will include the topic AND the parser's format instructions
+```
+
+This works with file-based templates too:
+
+```jinja
+# article_structured.jinja
+Write an article about {{ topic }}.
+
+Please format your response according to these instructions:
+{{ format_instructions }}
+```
+
+```python
+prompter = Prompter(
+    prompt_template="article_structured",
+    parser=parser
+)
+```
+
+The parser integration supports any LangChain output parser that implements `get_format_instructions()`, including:
+- `PydanticOutputParser` - For structured Pydantic model outputs
+- `OutputFixingParser` - For fixing malformed outputs
+- `RetryOutputParser` - For retrying failed parsing attempts
+- `StructuredOutputParser` - For dictionary-based structured outputs
+
 ### Including Other Templates
 
 You can include other template files within a template using Jinja2's `{% include %}` directive. This allows you to build modular templates.

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/notebooks/prompter_usage.ipynb

@@ -16,7 +16,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -36,7 +36,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
@@ -45,7 +45,7 @@
        "'Write an article about AI.'"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -71,7 +71,28 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'/Users/luisnovo/dev/projetos/ai-prompter/notebooks/prompts/article.jinja'"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "prompter = Prompter(prompt_template=\"article\") #will look for article.jinja in the prompts directory\n",
+    "prompter.template_location(\"article\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -80,7 +101,7 @@
        "'Write an article about AI.'"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -103,7 +124,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
     {
@@ -112,7 +133,7 @@
        "'This is the outer file \\n\\nThis is the inner file\\n\\nValue: a\\n\\n\\n    You selected A\\n\\n\\nThis is the end of the outer file'"
       ]
      },
-     "execution_count": 9,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -136,7 +157,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -145,7 +166,7 @@
        "ChatPromptTemplate(input_variables=['topic'], input_types={}, partial_variables={}, messages=[HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=['topic'], input_types={}, partial_variables={}, template='Write an article about {{topic}}.', template_format='jinja2'), additional_kwargs={})])"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -162,7 +183,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -171,7 +192,7 @@
        "ChatPromptTemplate(input_variables=['type'], input_types={}, partial_variables={}, messages=[HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=['type'], input_types={}, partial_variables={}, template=\"This is the outer file \\n\\nThis is the inner file\\n\\nValue: {{ type }}\\n\\n{% if type == 'a' %}\\n    You selected A\\n{% else %}\\n    You didn't select A\\n{% endif %}\\n\\n\\nThis is the end of the outer file\\n\", template_format='jinja2'), additional_kwargs={})])"
       ]
      },
-     "execution_count": 11,
+     "execution_count": 7,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -184,7 +205,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
@@ -193,7 +214,7 @@
        "ChatPromptValue(messages=[HumanMessage(content='This is the outer file \\n\\nThis is the inner file\\n\\nValue: a\\n\\n\\n    You selected A\\n\\n\\n\\nThis is the end of the outer file', additional_kwargs={}, response_metadata={})])"
       ]
      },
-     "execution_count": 12,
+     "execution_count": 8,
      "metadata": {},
      "output_type": "execute_result"
     }

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ai-prompter"
-version = "0.2.2"
+version = "0.3.0"
 description = "A prompt management library using Jinja2 templates to build complex prompts easily."
 readme = "README.md"
 homepage = "https://github.com/lfnovo/ai-prompter"
@@ -30,6 +30,7 @@ package-dir = {"ai_prompter" = "src/ai_prompter"}
 dev = [
     "ipykernel>=4.0.1",
     "ipywidgets>=4.0.0",
+    "langchain-core>=0.3.54",
     "pyperclip>=1.9.0",
     "pytest>=7.2.0",
     "pytest-asyncio>=0.21.0",

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/src/ai_prompter/__init__.py

@@ -5,7 +5,7 @@ A prompt management module using Jinja to generate complex prompts with simple t
 import os
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Any, Dict, Optional, Union, Callable
+from typing import Any, Dict, List, Optional, Union, Callable
 
 from jinja2 import Environment, FileSystemLoader, Template
 from pydantic import BaseModel
@@ -36,6 +36,8 @@ class Prompter:
     template: Optional[Union[str, Template]] = None
     template_text: Optional[str] = None
     parser: Optional[Any] = None
+    text_templates: Optional[Dict[str, str]] = None
+    prompt_folders: Optional[List[str]] = None
 
     def __init__(
         self,
@@ -69,6 +71,8 @@ class Prompter:
         self.parser = parser
         self.template: Template | None = None
         self.model = model or os.getenv("OPENAI_MODEL", "gpt-4-turbo")
+        self.text_templates = {}
+        self.prompt_folders = []
         self._setup_template(template_text, prompt_dir)
 
     def _setup_template(
@@ -93,16 +97,37 @@ class Prompter:
             prompts_path = os.getenv("PROMPTS_PATH")
             if prompts_path is not None:
                 prompt_dirs.extend(prompts_path.split(":"))
-            # Fallback to local folder and ~/ai-prompter
-            prompt_dirs.extend([os.getcwd(), os.path.expanduser("~/ai-prompter")])
+            
+            # Add current working directory + /prompts
+            cwd_prompts = os.path.join(os.getcwd(), "prompts")
+            if os.path.exists(cwd_prompts):
+                prompt_dirs.append(cwd_prompts)
+            
+            # Try to find project root and add its prompts folder
+            current_path = os.getcwd()
+            while current_path != os.path.dirname(current_path):  # Stop at root
+                # Check for common project indicators
+                if any(os.path.exists(os.path.join(current_path, indicator)) 
+                       for indicator in ['pyproject.toml', 'setup.py', 'setup.cfg', '.git']):
+                    project_prompts = os.path.join(current_path, "prompts")
+                    if os.path.exists(project_prompts) and project_prompts not in prompt_dirs:
+                        prompt_dirs.append(project_prompts)
+                    break
+                current_path = os.path.dirname(current_path)
+            
+            # Fallback to ~/ai-prompter
+            prompt_dirs.append(os.path.expanduser("~/ai-prompter"))
+            
             # Default package prompts folder
             if os.path.exists(prompt_path_default):
                 prompt_dirs.append(prompt_path_default)
             env = Environment(loader=FileSystemLoader(prompt_dirs))
             self.template = env.get_template(f"{self.prompt_template}.jinja")
+            self.prompt_folders = prompt_dirs
         else:
             self.template_text = template_text
             self.template = Template(template_text)
+            self.text_templates[self.prompt_template] = template_text
 
     def to_langchain(self):
         # Support for both text-based and file-based templates with LangChain
@@ -187,6 +212,28 @@ class Prompter:
                 "Either prompt_template with a valid template or template_text must be provided for LangChain conversion"
             )
 
+    def template_location(self, template_name: str) -> str:
+        """
+        Returns the location of the template used for the given template name.
+        If the template is a text template (not a file), returns 'text'.
+        If the template is not found, returns 'not found'.
+        
+        Args:
+            template_name (str): The name of the template to check.
+        
+        Returns:
+            str: The file path of the template, or 'text' if it's a text template, or 'not found' if the template doesn't exist.
+        """
+        if template_name in self.text_templates:
+            return 'text'
+        
+        for folder in self.prompt_folders:
+            template_file = os.path.join(folder, f"{template_name}.jinja")
+            if os.path.exists(template_file):
+                return template_file
+        
+        return 'not found'
+
     @classmethod
     def from_text(
         cls, text: str, model: Optional[Union[str, Any]] = None

{ai_prompter-0.2.2 → ai_prompter-0.3.0}/uv.lock

@@ -1,5 +1,4 @@
 version = 1
-revision = 1
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version < '3.12.4'",
@@ -8,7 +7,7 @@ resolution-markers = [
 
 [[package]]
 name = "ai-prompter"
-version = "0.2.2"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "jinja2" },
@@ -25,6 +24,7 @@ langchain = [
 dev = [
     { name = "ipykernel" },
     { name = "ipywidgets" },
+    { name = "langchain-core" },
     { name = "pyperclip" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -38,12 +38,12 @@ requires-dist = [
     { name = "pip", specifier = ">=25.0.1" },
     { name = "pydantic", specifier = ">=2.0" },
 ]
-provides-extras = ["langchain"]
 
 [package.metadata.requires-dev]
 dev = [
     { name = "ipykernel", specifier = ">=4.0.1" },
     { name = "ipywidgets", specifier = ">=4.0.0" },
+    { name = "langchain-core", specifier = ">=0.3.54" },
     { name = "pyperclip", specifier = ">=1.9.0" },
     { name = "pytest", specifier = ">=7.2.0" },
     { name = "pytest-asyncio", specifier = ">=0.21.0" },
@@ -352,7 +352,7 @@ name = "ipykernel"
 version = "6.29.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "appnope", marker = "sys_platform == 'darwin'" },
+    { name = "appnope", marker = "platform_system == 'Darwin'" },
     { name = "comm" },
     { name = "debugpy" },
     { name = "ipython" },