margarita 0.3.9

A lightweight markup language and Python library for writing, composing, and rendering structured LLM prompts.

MARGARITA

Margarita is a lightweight markup language and Python library for writing, composing, and rendering structured LLM prompts.

It renders out to Markdown format by default so you can use this anywhere Markdown is supported.

Margarita extends Markdown with templating features like variables, conditionals, loops, and includes, making it easy to create dynamic prompts for large language models (LLMs).

Features

• ✨ Framework agnostic — works with any LLM or API
• 🚀 Composable — prompts can be split, reused, and nested
• 🎯 Static-first — templates are validated before execution
• 📦 Metadata — version, and provide metadata alongside your prompts.

Installation

Run the following command for your platform to install MARGARITA using uv:

uv tool install margarita

or run it without installing:

uvx margarita render greeting.mg

Get Started

Here's a Hello World example. helloworld.mg contains the template, and helloworld.json contains the data.

// file:helloworld.mg
<<
Hello, ${name}!
Welcome to Margarita templating.
>>

// file:helloworld.json

{
    "name": "World"
}

Run the following command:

margarita render helloworld.mg

Output:

Hello, World!
Welcome to Margarita templating.

Conditionals Example

// file:conditional_example.mg

if is_admin:
    <<Welcome, Admin ${name}>>
else:
    <<Welcome, User ${name}!>>

Includes

// file: role_example.mg
<< You are a fancy AI assistant. >>

// files:json_output_format_template.mg
<<
Output the response in the following JSON format:
{
    "response": "<your response here>"
}
>>

// file:include_example.mg

[[ role ]]

if output_json:
    [[ json_output_format_template ]]

Passing Context

You can pass context variables to your templates to make them dynamic.

// file:role.mg
<<
You are a ${type} AI assistant.
>>

// file:context_example.mg
[[ role type="fancy" ]]

Metadata

Organize your templates with metadata headers.

// file:metadata_example.mg
---
title: "Greeting Template"
version: "1.0"
author: "Batman"
---
<<
Hello, ${name}!
Welcome to Margarita templating.
>>

Python Library

Install the package via pip/poetry/uv/etc or whatever package manager you prefer:

pip install margarita
poetry add margarita
uv add margarita

Use the library in your Python code:

from margarita.parser import Parser
from margarita.renderer import Renderer

template = """
<<
You are a helpful assistant.

Task: ${task}
>>
if context:
    <<
    Context:
        ${context}
    >>

<< Please provide a detailed response. >>
"""

# Parse the template
parser = Parser()
metadata, nodes = parser.parse(template)

# Create a renderer with context
renderer = Renderer(
    context={"task": "Summarize the key points", "context": "User is researching AI agents"}
)

# Render the output
prompt = renderer.render(nodes)
print(prompt)

Use the Composer to manage multiple templates:

from margarita.composer import Composer
from pathlib import Path

manager = Composer(Path("./templates"))

# Compose a complex prompt from multiple snippets
prompt = manager.compose_prompt(
    snippets=[
        "snippets/system_role.mg",
        "snippets/task_context.mg",
        "snippets/chain_of_thought.mg",
        "snippets/output_format.mg"
    ],
    context={
        "role": "data scientist",
        "user_name": "Bob",
        "task": "Analyze customer churn",
        "format": "JSON",
        "tone": "analytical"
    }
)

Documentation

Full documentation is available at https://banyango.mgithub.io/margarita/latest

Development

This project uses uv for dependency management.

Setup Development Environment

make install

Running Tests

# Run tests with pytest
make test

Code Quality

# Format code with ruff
make format

# Lint code and check for issues
make lint

Building the Package

# Build the package
uv build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to:

• Update tests as appropriate
• Follow the existing code style
• Update documentation for any changed functionality

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• Kyle Reczek - Initial work - Banyango

Acknowledgments

• Markdown

Changelog

See CHANGELOG.md for a history of changes to this project.

Support

If you encounter any problems or have questions, please open an issue.