Metadata-Version: 2.4
Name: margarita
Version: 0.1.0
Summary: A lightweight markup language and Python library for writing, composing, and rendering structured LLM prompts.
Project-URL: Homepage, https://github.com/Banyango/margarita
Project-URL: Documentation, https://banyango.github.io/margarita
Project-URL: Repository, https://github.com/Banyango/margarita
Project-URL: Issues, https://github.com/Banyango/margarita/issues
Project-URL: Changelog, https://github.com/Banyango/margarita/blob/main/CHANGELOG.md
Author-email: Kyle Reczek <kyle@banyango.com>
Maintainer-email: Kyle Reczek <kyle@banyango.com>
License: MIT
License-File: LICENSE
Keywords: llm,margarita,markup,prompt-engineering,templating
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: loguru>=0.7.3
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Description-Content-Type: text/markdown

# MARGARITA

[![PyPI version](https://badge.fury.io/py/margarita.svg)](https://badge.fury.io/py/margarita)
[![Python Support](https://img.shields.io/pypi/pyversions/margarita.svg)](https://pypi.org/project/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.

```markdown:helloworld.marg
// file:helloworld.marg

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

```json:helloworld.json
// file:helloworld.json

{
    "name": "World"
}
```

**Run the following command:**
```shell
margarita render helloworld.marg
```

**Output:**

```markdown
Hello, World!
Welcome to Margarita templating.
```


## Python Library

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

```bash
pip install margarita
poetry add margarita
uv add margarita
```

Use the library in your Python code:

```python
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:

```python
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](https://www.banyango.com/MARGARITA/latest/)

## Development

This project uses [uv](https://github.com/astral-sh/uv) for dependency management.

### Setup Development Environment

```bash
uv sync # Install dependencies
```

### Running Tests

```bash
# Run tests with pytest
uv run pytest

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

### Code Quality

```bash
# 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

```bash
# 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](LICENSE) file for details.

## Authors

- **Kyle Reczek** - *Initial work* - [Banyango](https://github.com/Banyango)

## Acknowledgments

- Markdown

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this project.

## Support

If you encounter any problems or have questions, please [open an issue](https://github.com/yourusername/margarita/issues).

