LLMUtils/README.md

LLMUtils

A Python utility library for managing LLM prompts with Jinja2 template support and JSON schemas.

Installation

Install using uv

uv add git+https://git.project-insanity.de/gmarth/LLMUtils.git

Install using pip

pip install git+https://git.project-insanity.de/gmarth/LLMUtils.git

Features

• Jinja2 Template Engine: Full support for loops, conditionals, filters, and complex data structures
• Smart Prompt Management: Load and manage prompt templates with variable substitution
• On-demand Loading: Prompts are loaded lazily at runtime for better performance
• Caching Support: Optional caching to avoid repeated disk reads
• JSON Schema Support: Associate structured output schemas with prompts
• Variable Validation: Automatic validation of required template variables
• Flexible API: Fill variables at retrieval or on-demand

Quick Start

Basic Usage

from llmutils.prompt_manager import PromptManager

# Get a prompt template
result = PromptManager.get_prompt('greeting')
print(result.variables)  # See required variables: {'name', 'age'}
print(result.template)   # View the template: "Hello {{name}}, you are {{age}} years old"

# Fill the template
filled = result.fill(name='Alice', age=30)
print(filled)  # "Hello Alice, you are 30 years old"

Pre-filling Variables

# Fill variables during retrieval
result = PromptManager.get_prompt('greeting', name='Alice', age=30)
print(result.prompt)  # Already filled: "Hello Alice, you are 30 years old"

Validation

result = PromptManager.get_prompt('greeting')

# Check if variables are valid
if not result.validate(name='Alice'):
    missing = result.get_missing_variables(name='Alice')
    print(f"Missing variables: {missing}")  # {'age'}

# Fill with all required variables
filled = result.fill(name='Alice', age=30)

Advanced Jinja2 Features

# Using lists and loops
result = PromptManager.get_prompt('task_list')
filled = result.fill(
    tasks=['Write code', 'Review PR', 'Deploy'],
    priority='high'
)

# Using conditionals
result = PromptManager.get_prompt('status_report')
filled = result.fill(
    error='Connection timeout',  # Will show error message
    items=[]  # Will show "No items"
)

# Using complex nested data
result = PromptManager.get_prompt('user_profile')
filled = result.fill(
    user={
        'name': 'Alice',
        'roles': ['admin', 'developer'],
        'projects': [
            {'name': 'Project A', 'status': 'active'},
            {'name': 'Project B', 'status': 'completed'}
        ]
    }
)

JSON Schema Support

# Get prompt with associated schema
result = PromptManager.get_prompt('task_prompt')

if result.schema:
    print("This prompt has a structured output schema")
    print(result.schema)  # The JSON schema dictionary

Configuration

from pathlib import Path
from llmutils.prompt_manager import PromptManager

# Configure custom prompts directory (default: ./prompts)
PromptManager.configure(path=Path('/custom/prompts/location'))

# Disable caching for development
PromptManager.configure(caching=False)

# Clear cache to force reload
PromptManager.reload_prompts()

Prompt Files

Place your prompt templates in the prompts/ directory:

• prompts/greeting.md - Markdown file with template
• prompts/greeting.json - Optional JSON schema for structured output

Simple Template Example (greeting.md):

Hello {{name}},

You are {{age}} years old.

Jinja2 Template Examples

Lists and Loops (task_list.md):

Priority: {{ priority }}

Tasks to complete:
{% for task in tasks %}
- {{ task }}
{% endfor %}

Total: {{ tasks | length }} tasks

Conditionals (status_report.md):

{% if error %}
⚠️ ERROR: {{ error }}
{% else %}
✅ All systems operational
{% endif %}

{% if items %}
Items ({{ items | length }}):
{% for item in items %}
  {{ loop.index }}. {{ item }}
{% endfor %}
{% else %}
No items to process.
{% endif %}

Complex Data (user_profile.md):

# User: {{ user.name }}

## Roles
{{ user.roles | join(', ') }}

## Projects
{% for project in user.projects %}
- {{ project.name }} [{{ project.status | upper }}]
{% endfor %}

JSON Schema Example (greeting.json):

{
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    }
  }
}

API Reference

ManagedPrompt Class

The ManagedPrompt dataclass returned by get_prompt():

• template: str - The original Jinja2 template string
• name: str - The prompt name
• variables: Set[str] - Required template variables (auto-extracted from Jinja2)
• schema: Optional[Dict] - Associated JSON schema
• prompt: str - Property that returns filled prompt or template
• fill(**kwargs) -> str - Fill template with variables using Jinja2
• validate(**kwargs) -> bool - Check if all variables provided
• get_missing_variables(**kwargs) -> Set[str] - Get missing variables

PromptManager Methods

• get_prompt(prompt_name, **kwargs) -> ManagedPrompt - Get a prompt template
• get_schema(prompt_name) -> Optional[Dict] - Get just the schema
• has_schema(prompt_name) -> bool - Check if prompt has schema
• list_prompts() -> Dict - List all available prompts
• get_prompt_info(prompt_name) -> Dict - Get detailed prompt information
• configure(path=None, caching=None) - Configure settings
• reload_prompts() - Clear the cache

Jinja2 Template Features

The library supports all standard Jinja2 features:

Filters

• {{ items | length }} - Get length of list
• {{ name | upper }} - Convert to uppercase
• {{ name | lower }} - Convert to lowercase
• {{ skills | join(', ') }} - Join list items
• {{ data | tojson }} - Convert to JSON
• {{ price | round(2) }} - Round numbers

Loops

• {% for item in items %}...{% endfor %} - Iterate over lists
• {{ loop.index }} - Current iteration (1-indexed)
• {{ loop.index0 }} - Current iteration (0-indexed)
• {% for key, value in dict.items() %}...{% endfor %} - Iterate over dictionaries

Conditionals

• {% if condition %}...{% endif %} - Simple conditional
• {% if condition %}...{% else %}...{% endif %} - If/else
• {% if condition %}...{% elif other %}...{% else %}...{% endif %} - Multiple conditions

License

MIT