init

README.md

@@ -1,2 +1,143 @@
 # LLMUtils
 
+A Python utility library for managing LLM prompts with template variables and JSON schemas.
+
+## Installation
+
+```bash
+# Install from GitHub
+uv add git+https://git.project-insanity.de/gmarth/LLMUtils.git
+
+# Or with pip
+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