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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-prompter
-Version: 0.2.3
+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.3 → 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.3 → ai_prompter-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ai-prompter"
-version = "0.2.3"
+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.3 → ai_prompter-0.3.0}/src/ai_prompter/__init__.py

@@ -97,8 +97,27 @@ 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)

{ai_prompter-0.2.3 → 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.3"
+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" },