Metadata-Version: 2.4
Name: liteprompt
Version: 0.2.10
Summary: Lightweight, extensible prompt templating for LLMs
Author: Gianluigi Mucciolo
License: MIT License
        
        Copyright (c) 2025 Gianluigi Mucciolo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=5.4
Requires-Dist: jinja2>=3.0
Requires-Dist: jinja2schema==0.1.4
Provides-Extra: aws
Requires-Dist: boto3==1.38.13; extra == "aws"
Provides-Extra: cache
Requires-Dist: cachetools==5.3.3; extra == "cache"
Provides-Extra: tokenizer
Requires-Dist: tiktoken==0.7.0; extra == "tokenizer"
Provides-Extra: gcs
Requires-Dist: google-cloud-storage==2.19.0; extra == "gcs"
Dynamic: license-file

# LitePrompt: A Flexible Template-Based Prompt Engineering Library

> **Scalability isn’t just about growing—it’s about staying lean and focusing on what truly matters. Flexibility isn’t just a feature; it’s the core of LitePrompt, built to adapt to your unique needs.**

`LitePrompt` is a Python library designed to provide a flexible and extensible system for managing and generating prompts for conversational AI systems. It leverages template-based prompt generation, with support for various storage backends, caching mechanisms, and structured prompt formats. The library allows developers to create complex, context-aware prompts with minimal setup and dependencies.

## Key Features

- **Template-based prompt generation**: Utilizes Jinja2 for flexible template rendering.
- **Multiple storage backends support**: Load templates from local files, Amazon S3, Google Cloud Storage, and local packages.
- **Built-in caching**: Optimizes performance by caching templates.
- **Role-based messaging**: Generates structured prompts with user, system, and assistant roles.
- **Multi-modal content**: Supports text, images, and file-based content.
- **Flexible template management**: Load and manage templates with ease.

## Usage Instructions

### Prerequisites

- **Python version**: >=3.10
- **Required packages**:
  * `PyYAML>=5.4`
  * `Jinja2>=3.0`
  * `Jinja2schema==0.1.4`
- **Optional packages** (install based on your use case):

  * `boto3` (for S3 support)
  * `google-cloud-storage` (for GCS support)
  * `tiktoken` (for token counting)
  * `cachetools`

### Installation

You can install `LitePrompt` using pip or directly from the source:

```bash
# Install via pip
pip install liteprompt

# Install from source
git clone https://github.com/ggiallo28/liteprompt.git
cd liteprompt
pip install .
```

### Quick Start

Here's a quick example of how to use `LitePrompt` to generate a prompt from a template:

```python
from liteprompt.loaders import LiteLocalFSTemplateLoader
from liteprompt.prompt import LitePrompt

# Create a template loader
loader = LiteLocalFSTemplateLoader(
    template_path="./templates/main_prompt.yml.j2"
)

# Define template data
template_data = {
    "character_name": "Ada",
    "username": "User",
    "user_query": "Hello!"
}

# Create and render prompt
prompt = LitePrompt(
    template_data=template_data,
    template_loader=loader
)

# Access generated messages
print(prompt.messages)
```

### More Detailed Examples

#### 1. Using Raw Templates:

```python
raw_template = """
- id: system_prompt
  role: system
  content: {{ content }}
"""

prompt = LitePrompt(
    raw_template=raw_template,
    template_data={"content": "You are a helpful assistant."}
)
```

#### 2. Multi-modal Content:

```python
raw_template = """
- id: user_parts
  role: user
  content:
    - type: text
      text: {{ text }}
    - type: image_url
      image_url:
        url: {{ image_url }}
        detail: high
"""

prompt = LitePrompt(
    raw_template=raw_template,
    template_data={
        "text": "Please analyze this image.",
        "image_url": "https://example.com/image.png"
    }
)
```

#### 3. Message Manipulation:

```python
# Create a base prompt
prompt = LitePrompt(raw_template=template, template_data=data)

# Replace an existing message
prompt.assign(
    at="chat_log_1",
    item=LiteMessage(
        id="chat_log_1",
        role="user",
        content="Alice: Can you help me with something?"
    )
)

# Append a message after a specific ID
prompt.append(
    item=LiteMessage(
        id="chat_log_3",
        role="assistant",
        content="Bot: Sure, what do you need help with?"
    ),
    after="chat_log_2"
)

# Prepend a message before everything
prompt.prepend(
    item=LiteMessage(
        id="system_msg",
        role="system",
        content="System: Starting new chat session."
    )
)

# Get list of message IDs
message_ids = prompt.list_message_ids()
```


## Template Management and Structure

The `LitePrompt` library utilizes a flexible system for loading and managing templates, which can be stored across different backends such as local files, cloud storage (S3, Google Cloud), or packaged templates. The default template loader is capable of handling various types of prompt templates that are structured into multiple sections for different use cases.

### Default Loader Functionality

The default loader is designed to load templates from the local filesystem, allowing for an organized and modular template structure. It supports various types of templates, including:

- **Agent Prompts**: These templates define different agent behaviors, such as interactive, memory-based, or task-specific agents.
- **Procedure Prompts**: Templates focused on guiding an agent through specific steps or procedures, including detailed instructions, context, and summaries.
- **Memory-Based Prompts**: Templates for managing memory-related tasks, like recalling past interactions or episodic memories.
- **Tool and System Prompts**: Templates that help integrate tools or system-level instructions with the conversational flow.
- **User Query and Response Templates**: Specific templates for handling user queries, formulating responses, and managing chat histories.

These templates are stored within subdirectories, allowing for easy organization and flexibility when adding or updating individual components. The system is designed to load only the relevant templates based on the specific requirements of the prompt generation, making it efficient for creating context-aware and dynamic interactions.

The default loader seamlessly integrates these templates into the prompt generation process, allowing developers to specify the path and context for each prompt while maintaining clean separation of concerns across the different sections of the prompt.


### Troubleshooting

#### Common Issues and Solutions:

1. **Missing Dependencies**:

   * Error: `ImportError: 'boto3' is required but not installed`
   * Solution: `pip install boto3`

2. **Template Not Found**:

   * Ensure the template path is correct:

   ```python
   loader = LiteLocalFSTemplateLoader(
       template_path="./absolute/path/to/template.yml.j2"
   )
   ```

3. **Template Rendering Errors**:

   * Check for syntax errors in the template.
   * Ensure all required template variables are provided.
   * Enable debug logging to inspect errors:

   ```python
   import logging
   logging.basicConfig(level=logging.DEBUG)
   ```

## Data Flow

The flow of data through the `LitePrompt` system involves multiple components that work together to generate formatted prompts for AI models:

```ascii
[Template Source] -> [Template Loader] -> [Template Engine]
         |                                      |
         v                                      v
    [Template Cache] <- [Prompt Generator] -> [Formatted Messages]
         ^                     |
         |                     v
[Template Registry]    [Content Validation]
```

### Component Interactions:

1. **Template Loaders**: Fetch templates from various sources like local files, Amazon S3, Google Cloud Storage, or local packages.
2. **Template Cache**: Caches templates to improve performance.
3. **Template Engine (Jinja2)**: Renders templates with provided data.
4. **Prompt Generator**: Creates structured message formats, ready to be used by AI models.
5. **Content Validation**: Ensures the correctness of the rendered content, such as proper formatting and required fields.
6. **Template Registry**: Manages template discovery and versioning for reuse.
7. **Cache System**: Optimizes template loading for faster response times.

## Why Choose `LitePrompt`?

`LitePrompt` is designed to be a flexible, efficient, and lightweight solution for managing prompts in conversational AI systems. Its modular architecture separates core functionality from advanced features, so you only install what you actually need. Whether you're working with local files, cloud storage, or caching, the library adapts to your workflow without unnecessary bloat.

At the heart of LitePrompt is a philosophy of practical scalability—not just the ability to grow, but the freedom to stay small and focused. Every feature is plug-and-play, every dependency is optional, and every implementation puts your specific needs first. LitePrompt stays lean so you can move fast, customize freely, and scale only when and how it makes sense for you—even if that means rewriting part of the code to fit your use case.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

## Contributing

We welcome contributions!
