lfnovo/ai-prompter

pip install ai-prompter

# For LangChain integration
pip install ai-prompter[langchain]

from ai_prompter import Prompter

# Create a simple prompt template
prompter = Prompter(template_text="""
You are a {{ role }} expert. Help the user with their {{ task_type }} question.

User Question: {{ question }}

Please provide a {{ tone }} and detailed response.
""")

# Use it with different scenarios
response = prompter.render({
    "role": "Python programming",
    "task_type": "debugging", 
    "question": "Why is my list comprehension not working?",
    "tone": "friendly"
})

print(response)
# Output: You are a Python programming expert. Help the user with their debugging question...

<!-- prompts/code_review.jinja -->
You are an experienced {{ language }} developer conducting a code review.

Code to review:
```{{ language }}
{{ code }}

```python
from ai_prompter import Prompter

# Load the template by name (finds prompts/code_review.jinja automatically)
reviewer = Prompter(prompt_template="code_review")

prompt = reviewer.render({
    "language": "python",
    "code": "def calculate(x, y): return x + y",
    "focus_areas": ["error handling", "documentation", "performance"]
})

# Install from PyPI
pip install ai-prompter

# Or using uv (recommended for Python projects)
uv add ai-prompter

pip install ai-prompter[langchain]
# or
uv add ai-prompter[langchain]

git clone https://github.com/lfnovo/ai-prompter
cd ai-prompter
uv sync  # installs with all dev dependencies

PROMPTS_PATH=path/to/custom/templates

from ai_prompter import Prompter

# Initialize with a template name
prompter = Prompter('my_template')

# Render a prompt with variables
prompt = prompter.render({'variable': 'value'})
print(prompt)

prompter = Prompter(template_text='Hello {{ name }}!', prompt_dir='/path/to/your/prompts')

export PROMPTS_PATH=/path/to/your/prompts

export PROMPTS_PATH=/path/to/templates1:/path/to/templates2

my-project/
├── prompts/           # <- Templates here will be found automatically
│   └── my_template.jinja
├── src/
│   └── my_package/
│       └── main.py
└── pyproject.toml

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

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)  # Uses greet.jinja from the first path where it's found

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.

from ai_prompter import Prompter

# Using template_text parameter
prompter = Prompter(template_text="Hello, {{ name }}!")
result = prompter.render({"name": "World"})
print(result)  # Output: Hello, World!

# Using from_text class method
prompter = Prompter.from_text("Hi, {{ person }}!", model="gpt-4")
result = prompter.render({"person": "Alice"})
print(result)  # Output: Hi, Alice!

from ai_prompter import Prompter

# With text-based template
text_prompter = Prompter(template_text="Hello, {{ name }}!")
lc_text_prompt = text_prompter.to_langchain()

# With file-based template
file_prompter = Prompter(prompt_template="greet")
lc_file_prompt = file_prompter.to_langchain()

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

# article_structured.jinja
Write an article about {{ topic }}.

Please format your response according to these instructions:
{{ format_instructions }}

prompter = Prompter(
    prompt_template="article_structured",
    parser=parser
)

# prompts/blog_post.jinja
You are a professional content writer specializing in {{ niche }}.

Write a {{ post_type }} blog post about "{{ title }}" for {{ target_audience }}.

Requirements:
- Length: {{ word_count }} words
- Tone: {{ tone }}
- Include {{ num_sections }} main sections
{% if seo_keywords -%}
- SEO Keywords to include: {{ seo_keywords|join(', ') }}
{% endif %}
{% if call_to_action -%}
- End with this call-to-action: {{ call_to_action }}
{% endif %}

{{ format_instructions }}

from ai_prompter import Prompter
from pydantic import BaseModel, Field

class BlogPost(BaseModel):
    title: str = Field(description="SEO-optimized title")
    sections: list[dict] = Field(description="List of sections with headers and content")
    meta_description: str = Field(description="SEO meta description")
    tags: list[str] = Field(description="Relevant tags")

# Create content generator
blog_generator = Prompter(
    prompt_template="blog_post",
    parser=PydanticOutputParser(pydantic_object=BlogPost)
)

# Generate different types of content
tech_post = blog_generator.render({
    "niche": "technology",
    "title": "Getting Started with AI Prompt Engineering", 
    "target_audience": "software developers",
    "post_type": "how-to guide",
    "word_count": 1500,
    "tone": "technical but accessible",
    "num_sections": 5,
    "seo_keywords": ["AI prompts", "prompt engineering", "LLM"],
    "call_to_action": "Try AI Prompter in your next project!"
})

# prompts/customer_support.jinja
{% set greetings = {
    'en': 'Hello',
    'es': 'Hola', 
    'fr': 'Bonjour',
    'de': 'Hallo'
} %}

{{ greetings[language] }}! I'm here to help you with {{ issue_type }}.

Customer Issue: {{ customer_message }}

{% if language != 'en' -%}
Please respond in {{ language }}.
{% endif %}

Provide a {{ tone }} response that:
1. Acknowledges the customer's concern
2. Offers a specific solution or next steps
3. Includes relevant {{ company_name }} policies if applicable

support_agent = Prompter(prompt_template="customer_support")

# Handle support tickets in different languages
spanish_response = support_agent.render({
    "language": "es",
    "issue_type": "billing inquiry",
    "customer_message": "No puedo encontrar mi factura",
    "tone": "empathetic and professional",
    "company_name": "TechCorp"
})

# prompts/email_campaign.jinja
Subject: {% if user.is_premium %}Exclusive{% else %}Special{% endif %} {{ campaign_type }} - {{ subject_line }}

Hi {{ user.first_name|default('there') }},

{% if user.last_purchase_days_ago < 30 -%}
Thanks for your recent purchase of {{ user.last_product }}! 
{% elif user.last_purchase_days_ago > 90 -%}
We miss you! It's been a while since your last order.
{% endif %}

{{ main_message }}

{% if user.is_premium -%}
As a premium member, you get:
{% for benefit in premium_benefits -%}
✓ {{ benefit }}
{% endfor %}
{% else -%}
{% if upgrade_offer -%}
Upgrade to premium and save {{ upgrade_discount }}%!
{% endif %}
{% endif %}

{{ call_to_action }}

Best regards,
{{ sender_name }}

email_generator = Prompter(prompt_template="email_campaign")

# Personalized emails based on user data
campaign_email = email_generator.render({
    "user": {
        "first_name": "Sarah",
        "is_premium": False,
        "last_purchase_days_ago": 45,
        "last_product": "Python Course"
    },
    "campaign_type": "Sale",
    "subject_line": "50% Off All Programming Courses",
    "main_message": "Master new skills with our comprehensive programming courses.",
    "upgrade_offer": True,
    "upgrade_discount": 25,
    "premium_benefits": ["Early access to new courses", "1-on-1 mentoring", "Certificate priority"],
    "call_to_action": "Shop Now →",
    "sender_name": "The Learning Team"
})

# prompts/api_docs.jinja
# {{ endpoint.method }} {{ endpoint.path }}

{{ endpoint.description }}

## Request

{% if endpoint.parameters -%}
### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
{% for param in endpoint.parameters -%}
| `{{ param.name }}` | {{ param.type }} | {{ "Yes" if param.required else "No" }} | {{ param.description }} |
{% endfor %}
{% endif %}

{% if endpoint.body_schema -%}
### Request Body

```json
{{ endpoint.body_schema|tojson(indent=2) }}

{{ endpoint.response_example|tojson(indent=2) }}

curl -X {{ endpoint.method }} "{{ base_url }}{{ endpoint.path }}" \
{% for header in endpoint.headers -%}
  -H "{{ header.name }}: {{ header.value }}" \
{% endfor %}
{% if endpoint.body_example -%}
  -d '{{ endpoint.body_example|tojson }}'
{% endif %}

```python
docs_generator = Prompter(prompt_template="api_docs")

endpoint_doc = docs_generator.render({
    "base_url": "https://api.example.com",
    "endpoint": {
        "method": "POST",
        "path": "/users",
        "description": "Create a new user account",
        "parameters": [
            {"name": "api_key", "type": "string", "required": True, "description": "Your API key"}
        ],
        "body_schema": {"name": "string", "email": "string", "role": "string"},
        "body_example": {"name": "John Doe", "email": "[email protected]", "role": "user"},
        "response_example": {"id": 123, "name": "John Doe", "created_at": "2024-01-01T00:00:00Z"},
        "error_codes": [
            {"code": 400, "description": "Invalid request data"},
            {"code": 409, "description": "Email already exists"}
        ],
        "headers": [{"name": "Authorization", "value": "Bearer YOUR_API_KEY"}]
    }
})

prompts/
├── content/
│   ├── blog_post.jinja
│   ├── social_media.jinja
│   └── email_newsletter.jinja
├── analysis/
│   ├── code_review.jinja
│   ├── data_analysis.jinja
│   └── competitor_research.jinja
└── support/
    ├── customer_support.jinja
    └── technical_troubleshooting.jinja

# Good ✅
prompter.render({
    "user_expertise_level": "beginner",
    "preferred_learning_style": "visual",
    "target_completion_time": "2 weeks"
})

# Avoid ❌
prompter.render({
    "level": "beginner", 
    "style": "visual",
    "time": "2 weeks"
})

<!-- prompts/content_generator.jinja -->
{% if not topic -%}
{{ raise_error("topic is required") }}
{% endif %}

Generate content about {{ topic }} for {{ audience|default("general audience") }}.

Word count: {{ word_count|default(500) }}
Tone: {{ tone|default("professional") }}

<!-- Use filters for formatting -->
Today's date: {{ current_time|strftime("%B %d, %Y") }}
Uppercase title: {{ title|upper }}
Comma-separated tags: {{ tags|join(", ") }}

<!-- Use conditionals for dynamic content -->
{% if user.subscription_type == "premium" %}
You have access to premium features!
{% else %}
Upgrade to premium for advanced features.
{% endif %}

<!-- Use loops for repetitive content -->
{% for step in instructions %}
{{ loop.index }}. {{ step }}
{% endfor %}

# Track prompt changes with git
git add prompts/
git commit -m "feat: add support for multi-language customer service prompts"

# Use branches for prompt experiments  
git checkout -b experiment/new-tone-testing

# Create test data for your templates
test_data = {
    "user": {"name": "Test User", "level": "beginner"},
    "product": {"name": "AI Course", "price": 99.99},
    "current_time": "2024-01-15 10:30:00"
}

# Test all your templates
for template_name in ["welcome", "product_recommendation", "follow_up"]:
    prompter = Prompter(prompt_template=template_name)
    result = prompter.render(test_data)
    print(f"Template: {template_name}")
    print(f"Length: {len(result)} characters")
    print("---")

# outer.jinja
This is the outer file

{% include 'inner.jinja' %}

This is the end of the outer file

# inner.jinja
This is the inner file

{% if type == 'a' %}
    You selected A
{% else %}
    You didn't select A
{% endif %}

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

from ai_prompter import Prompter

prompter = Prompter(template_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!

from ai_prompter import Prompter

prompter = Prompter(template_text="Current time: {{current_time}}")
prompt = prompter.render()
print(prompt)  # Current time: 2025-04-19 23:28:00

Write an article about {{ topic }}.

from ai_prompter import Prompter

prompter = Prompter(prompt_template="article")
prompt = prompter.render({"topic": "AI"})
print(prompt)

# Check where AI Prompter is looking for templates
prompter = Prompter(prompt_template="my_template")
print("Template locations searched:")
for folder in prompter.prompt_folders:
    print(f"  - {folder}")

# Verify template location
location = prompter.template_location("my_template") 
print(f"Template location: {location}")

# Test templates in isolation
from jinja2 import Template

template_content = "Hello {{ name }}!"
template = Template(template_content)
result = template.render(name="World")  # Test basic rendering

# Check current PROMPTS_PATH
echo $PROMPTS_PATH

# Set for current session
export PROMPTS_PATH="/path/to/templates"

# Set permanently in ~/.bashrc or ~/.zshrc  
echo 'export PROMPTS_PATH="/path/to/templates"' >> ~/.bashrc

# Good: Reuse prompter instances
email_prompter = Prompter(prompt_template="email_template")
for user in users:
    email = email_prompter.render({"user": user})
    send_email(email)

# Avoid: Creating new instances repeatedly  
for user in users:  # Less efficient
    prompter = Prompter(prompt_template="email_template")
    email = prompter.render({"user": user})

# Clone the repository
git clone https://github.com/lfnovo/ai-prompter
cd ai-prompter

# Install with dev dependencies
uv sync

# Launch Jupyter notebook
uv run jupyter lab notebooks/prompter_usage.ipynb

# Run all tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=ai_prompter

# Run specific test file
uv run pytest tests/test_prompter.py -v

# Format code
uv run black src/
uv run isort src/

pip install ai-prompter