margarita 0.1.0

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.

Margarita targets prompt engineering workflows where clarity, versioning, and correctness matter.

| FOR NOW! CLI tool is WIP you will need to download the source and install it locally to use the margarita command. |

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.

Get Started

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

// file:helloworld.marg

Hello, {{name}}!
Welcome to Margarita templating.

// file:helloworld.json

{
    "name": "World"
}

Run the following command:

margarita render helloworld.marg

Output:

Hello, World!
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}}
{% endif %}

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.marg",
        "snippets/task_context.marg",
        "snippets/chain_of_thought.marg",
        "snippets/output_format.marg"
    ],
    context={
        "role": "data scientist",
        "user_name": "Bob",
        "task": "Analyze customer churn",
        "format": "JSON",
        "tone": "analytical"
    }
)

Documentation

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

Development

This project uses uv for dependency management.

Setup Development Environment

uv sync # Install dependencies

Running Tests

# Run tests with pytest
uv run pytest

# Run tests with coverage
uv run pytest --cov=margarita --cov-report=html

Code Quality

# Format code with ruff
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking with mypy
uv run mypy src/margarita

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.