148 lines
3.8 KiB
Markdown
148 lines
3.8 KiB
Markdown
# LLMUtils
|
|
|
|
A Python utility library for managing LLM prompts with template variables and JSON schemas.
|
|
|
|
## Installation
|
|
|
|
### Install using uv
|
|
|
|
```bash
|
|
uv add git+https://git.project-insanity.de/gmarth/LLMUtils.git
|
|
```
|
|
|
|
### Install using pip
|
|
|
|
```bash
|
|
pip install git+https://git.project-insanity.de/gmarth/LLMUtils.git
|
|
```
|
|
|
|
## Features
|
|
|
|
- **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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
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)
|
|
```
|
|
|
|
### JSON Schema Support
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
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
|
|
|
|
Example prompt template (`greeting.md`):
|
|
```markdown
|
|
Hello {{name}},
|
|
|
|
You are {{age}} years old.
|
|
```
|
|
|
|
Example schema (`greeting.json`):
|
|
```json
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"response": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### PromptResult Class
|
|
|
|
The `PromptResult` dataclass returned by `get_prompt()`:
|
|
|
|
- `template: str` - The original template string
|
|
- `name: str` - The prompt name
|
|
- `variables: Set[str]` - Required template variables
|
|
- `schema: Optional[Dict]` - Associated JSON schema
|
|
- `prompt: str` - Property that returns filled prompt or template
|
|
- `fill(**kwargs) -> str` - Fill template with variables
|
|
- `validate(**kwargs) -> bool` - Check if all variables provided
|
|
- `get_missing_variables(**kwargs) -> Set[str]` - Get missing variables
|
|
|
|
### PromptManager Methods
|
|
|
|
- `get_prompt(prompt_name, **kwargs) -> PromptResult` - 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
|
|
|
|
## License
|
|
|
|
MIT
|