# CedarTL
A lightweight, intuitive templating language designed for interactive use in LLM chat sessions.
[![PyPI version](https://badge.fury.io/py/cedartl.svg)](https://pypi.org/project/cedartl/)
[![Python Versions](https://img.shields.io/pypi/pyversions/cedartl.svg)](https://pypi.org/project/cedartl/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
## Overview
CedarTL is a non-intrusive, recursive templating language that seamlessly integrates with LLM chat sessions.
Its simple syntax minimizes cognitive overhead while maximizing speed,
making it perfect for interactive development sessions.
## Table of Contents
- [Why should I use it?](#why-should-i-use-it)
- [For LLM Users](#for-llm-users)
- [For AI Code Assistant / IDE Developers](#for-ai-code-assistant--ide-developers)
- [Key Features](#key-features)
- [Syntax](#syntax)
- [Basic syntax](#basic-syntax)
- [FolderDict context folder control](#folderdict-context-folder-control)
- [Template management](#template-management)
- [LLM Control](#llm-control)
- [FolderDict](#folderdict)
- [Quick Start](#quick-start)
- [Concrete Example](#concrete-example)
- [Context](#context)
- [Chat Session](#chat-session-in-cedarml-format)
- [What's Next?](#whats-next)
- [Contributing](#contributing)
## Why should I use it?
It can save you time when writing your prompts.
Frequently-used pieces of text can be stored in named _templates_.
Then, instead of typing the same text over and over, you just put a reference to the named template.
- [**Templating via folders**](#folderdict): Frequently used prompts are stored as text files _grouped in a `context folder`_
- **Intuitive References**: Access templates using simple `\name` syntax
### For LLM Users:
See the [concrete example](#concrete-example) to see how easy the syntax is.
### For AI Code Assistant / IDE Developers:
See the [quick start](#quick-start) section if you want to support `CedarTL` in your product
## Key Features:
1. 🚀 Minimal Syntax: Clean, intuitive syntax that feels natural
- Designed to blend naturally with the target text, minimizing typing overhead
2. 🤖 **LLM-Optimized**: Built specifically for LLM interactions
3. 🔄 **Recursive Processing**: It can process templates within templates, allowing for nested template structures
4. 🔗 **Hierarchical** key access and function calls
5. 📁 Smart Folder-based templating through `FolderDict`
- Structure your templates logically in different `context folders` (accessing local directories, tar/zip files, and remote servers via WebDAV, HTTP, FTP, etc)
- Easy to switch between different contexts (See `\%cd`)
- Multiple contexts can be layered (using _most-recent-wins_ strategy)
6. 🖥️ Shell command Integration
You provide the `CedarTL` runtime a _root context_: a `dict`, a `list`, an object, or a [`FolderDict`](#folderdict)
(a path to a directory where its contained files are the keys, and the file contents are the values)
## Syntax
To escape to `CedarTL` syntax, you type a backslash and then a symbol. Examples:
### Basic syntax:
- `\name`: Key lookup.
- `\path/to/key`: Nested Key lookup
### FolderDict context folder control:
- `\..`: Move up one level in the context hierarchy
- `\%cd(<path-spec-1> <path-spec-2>...)`: Change the current `context folder` from where template keys and values are read
- `\%pwd`: Print current working context folder
- `\%ls`: List contents of current working context folder
### Template management:
- `\%set(key="value")`: Set volatile template value
- `\%get(key)`: Get the value associated with a key
- `\%saveas(<target-path>)`: Save the current template to a folder
- `\%load(<path>)`: Load template into volatile area
### LLM Control
- `\*chat(some text)`: LLM chat (starts a separate LLM session)
- `\*temp(<float>)`: LLM temperature control
... more to come
## FolderDict
A `FolderDict` is simply a way to view a folder (the `context folder`) as if it were a `dict` (that is, a mapping between keys and values).
In `Python`, it's compatible with type `dict[str, str]`.
Example: Inside a `resources` folder, we've added a folder named `templates` to hold different context folders. We want to view the `main` context folder as a `dict`,
so we point a `FolderDict` to that `main` folder:
```text
resources/
└── templates/
└── main/
├── fsninja.txt
├── l0.txt
├── rar.txt
└── sbs.txt
```
In the case above, the keys are:
1. `fsninja` (a full-stack ninja)
2. `l0` (for _**L**evel_ zero)
3. `rar` (for _Rephrase And Respond_)
4. `sbs` (for thinking _step-by-step_)
Notice that key names should represent the concept contained in the files.
However, all names above are arbitrary: `FolderDict` will work regardless of the names involved.
And where are the values for the keys?
Yes, the file _contents_ are the values for their corresponding keys.
By storing templates in a `FolderDict`, we get some advantages:
- Each folder can have specialized prompts for a specific type of task
- It's easier to share your template folder with the community (just zip it)
- It's easier to version-control a template folder
## Quick Start
```bash
pip install cedartl
```
```python
from cedartl import CedarTLProcessor
from importlib.resources import files
# [...]
class ExistingClass:
def __init__(self):
self.template_processor = CedarTLProcessor(files('resources.templates.main'))
def process_user_input(self, input: str):
# ...
processed_input: str = self.template_processor.process(input)
# ...
```
## Concrete Example
Real chat session using `CedarTL` with `qwen-2.5-72b-instruct` and Aider:
### Context
In this example, we're using a patched version of Aider that adds support for `CedarTL` inside chat sessions.
(Check the [FolderDict section](#folderdict) to see the names of the templates we're using here)
Aider delegates template processing to the `CedarTL` engine, which returns the final rendition of the text to be sent
to the LLM.
### Chat session in `CedarML` format:
(see [CedarML](https://github.com/CedarVerse/cedarml?tab=readme-ov-file#readme) for more info)
```xml
<cedarml:tool-in.aider>
/add aider/coders/base_coder.py
</cedarml:tool-in.aider>
<cedarml:tool-out.aider>
Added /GitHub/aider/aider/coders/base_coder.py to the chat
─────────
aider/coders/base_coder.py
</cedarml:tool-out.aider>
<cedarml:tool-in.cedartl>
what does this file do? \l0
</cedarml:tool-in.cedartl>
<cedarml:tool-out.cedartl>
\l0: \rar\sbs
\rar: Rephrase my request, then respond.
\sbs: Do so by thinking step by step.
</cedarml:tool-out.cedartl>
<cedarml:role.user>
what does this file do? Rephrase my request, then respond.
Do so by thinking step by step.
</cedarml:role.user>
<cedarml:role.assistant>
Sure, let's break down your request and then respond step by step.
Rephrased Request:
"Can you explain the purpose and main functionalities of the aider/coders/base_coder.py file?"
Step-by-Step Response:
1. File Overview:
• The aider/coders/base_coder.py file is a Python module that defines the Coder class and related functionalities.
• This class is a core component of the Aider application, which is designed to assist users in coding tasks using AI.
</cedarml:role.assistant>
```
<details>
<summary>Actual chat session screenshot</summary>
![img.png](img.png)
</details>
## What's Next?
Here's what's on the horizon for `CedarTL`:
- **Browser Extension**
- Cross-platform extension for seamless template access in any web text input
- Support for popular platforms:
- LLM web interfaces ([Kagi Assistant](https://kagi.com/assistant), ChatGPT, Claude, OpenRouter, etc.)
- Messaging apps (WhatsApp Web, Google Chat)
- Online text editors
- Social media platforms like Facebook, Instagram
- Features:
- Local template storage and management
- Secure sync across devices
- Template preview on hover
- Context-aware template auto-complete
- Integration with browser's autofill system
- Smart template generation from frequently typed text
- **Core Enhancements**
- Template sharing ecosystem
- More backend storage options (databases, cloud storage)
- Better template versioning
- **Integration APIs**
- SDK for easy integration into other applications
## Contributing
Want to contribute? Check out our [GitHub issues](https://github.com/YourRepo/CedarTL/issues) or propose new features!
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Raw data
{
"_id": null,
"home_page": null,
"name": "cedartl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "llm, templating, productivity, ai-development, code-generation, prompt-engineering, prompt-management, language-processing, development-tools",
"author": null,
"author_email": "Elifarley <cedarscript@orgecc.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/f5/6d7728b0ebbc8a2a8942c46a85048aabec25d83c1735e862feeaa05517f9/cedartl-0.1.1.tar.gz",
"platform": null,
"description": "# CedarTL\nA lightweight, intuitive templating language designed for interactive use in LLM chat sessions.\n\n[![PyPI version](https://badge.fury.io/py/cedartl.svg)](https://pypi.org/project/cedartl/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/cedartl.svg)](https://pypi.org/project/cedartl/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n\n\n\n## Overview\n\nCedarTL is a non-intrusive, recursive templating language that seamlessly integrates with LLM chat sessions.\nIts simple syntax minimizes cognitive overhead while maximizing speed,\nmaking it perfect for interactive development sessions.\n\n## Table of Contents\n- [Why should I use it?](#why-should-i-use-it)\n - [For LLM Users](#for-llm-users)\n - [For AI Code Assistant / IDE Developers](#for-ai-code-assistant--ide-developers)\n- [Key Features](#key-features)\n- [Syntax](#syntax)\n - [Basic syntax](#basic-syntax)\n - [FolderDict context folder control](#folderdict-context-folder-control)\n - [Template management](#template-management)\n - [LLM Control](#llm-control)\n- [FolderDict](#folderdict)\n- [Quick Start](#quick-start)\n- [Concrete Example](#concrete-example)\n - [Context](#context)\n - [Chat Session](#chat-session-in-cedarml-format)\n- [What's Next?](#whats-next)\n- [Contributing](#contributing)\n\n## Why should I use it?\nIt can save you time when writing your prompts.\n\nFrequently-used pieces of text can be stored in named _templates_.\nThen, instead of typing the same text over and over, you just put a reference to the named template.\n\n- [**Templating via folders**](#folderdict): Frequently used prompts are stored as text files _grouped in a `context folder`_\n- **Intuitive References**: Access templates using simple `\\name` syntax\n\n### For LLM Users:\nSee the [concrete example](#concrete-example) to see how easy the syntax is.\n\n### For AI Code Assistant / IDE Developers:\nSee the [quick start](#quick-start) section if you want to support `CedarTL` in your product\n\n## Key Features:\n1. \ud83d\ude80 Minimal Syntax: Clean, intuitive syntax that feels natural\n - Designed to blend naturally with the target text, minimizing typing overhead\n2. \ud83e\udd16 **LLM-Optimized**: Built specifically for LLM interactions\n3. \ud83d\udd04 **Recursive Processing**: It can process templates within templates, allowing for nested template structures\n4. \ud83d\udd17 **Hierarchical** key access and function calls\n5. \ud83d\udcc1 Smart Folder-based templating through `FolderDict`\n - Structure your templates logically in different `context folders` (accessing local directories, tar/zip files, and remote servers via WebDAV, HTTP, FTP, etc)\n - Easy to switch between different contexts (See `\\%cd`)\n - Multiple contexts can be layered (using _most-recent-wins_ strategy)\n6. \ud83d\udda5\ufe0f Shell command Integration\n\nYou provide the `CedarTL` runtime a _root context_: a `dict`, a `list`, an object, or a [`FolderDict`](#folderdict)\n(a path to a directory where its contained files are the keys, and the file contents are the values)\n\n## Syntax\nTo escape to `CedarTL` syntax, you type a backslash and then a symbol. Examples:\n\n### Basic syntax:\n- `\\name`: Key lookup.\n- `\\path/to/key`: Nested Key lookup\n\n### FolderDict context folder control:\n- `\\..`: Move up one level in the context hierarchy\n- `\\%cd(<path-spec-1> <path-spec-2>...)`: Change the current `context folder` from where template keys and values are read\n- `\\%pwd`: Print current working context folder\n- `\\%ls`: List contents of current working context folder\n\n### Template management:\n- `\\%set(key=\"value\")`: Set volatile template value\n- `\\%get(key)`: Get the value associated with a key\n- `\\%saveas(<target-path>)`: Save the current template to a folder\n- `\\%load(<path>)`: Load template into volatile area\n\n### LLM Control\n- `\\*chat(some text)`: LLM chat (starts a separate LLM session)\n- `\\*temp(<float>)`: LLM temperature control\n\n... more to come\n\n## FolderDict\nA `FolderDict` is simply a way to view a folder (the `context folder`) as if it were a `dict` (that is, a mapping between keys and values).\nIn `Python`, it's compatible with type `dict[str, str]`.\n\nExample: Inside a `resources` folder, we've added a folder named `templates` to hold different context folders. We want to view the `main` context folder as a `dict`,\nso we point a `FolderDict` to that `main` folder:\n\n```text\nresources/\n\u2514\u2500\u2500 templates/\n \u2514\u2500\u2500 main/\n \u251c\u2500\u2500 fsninja.txt\n \u251c\u2500\u2500 l0.txt\n \u251c\u2500\u2500 rar.txt\n \u2514\u2500\u2500 sbs.txt\n```\n\nIn the case above, the keys are:\n1. `fsninja` (a full-stack ninja)\n2. `l0` (for _**L**evel_ zero)\n3. `rar` (for _Rephrase And Respond_)\n4. `sbs` (for thinking _step-by-step_)\n\nNotice that key names should represent the concept contained in the files.\nHowever, all names above are arbitrary: `FolderDict` will work regardless of the names involved.\n\nAnd where are the values for the keys?\nYes, the file _contents_ are the values for their corresponding keys.\n\nBy storing templates in a `FolderDict`, we get some advantages:\n- Each folder can have specialized prompts for a specific type of task\n- It's easier to share your template folder with the community (just zip it)\n- It's easier to version-control a template folder\n\n## Quick Start\n\n```bash\npip install cedartl\n```\n\n```python\nfrom cedartl import CedarTLProcessor\nfrom importlib.resources import files\n\n# [...]\nclass ExistingClass:\n def __init__(self):\n self.template_processor = CedarTLProcessor(files('resources.templates.main'))\n def process_user_input(self, input: str):\n # ...\n processed_input: str = self.template_processor.process(input)\n # ...\n```\n\n## Concrete Example\nReal chat session using `CedarTL` with `qwen-2.5-72b-instruct` and Aider:\n\n### Context\nIn this example, we're using a patched version of Aider that adds support for `CedarTL` inside chat sessions.\n(Check the [FolderDict section](#folderdict) to see the names of the templates we're using here)\n\nAider delegates template processing to the `CedarTL` engine, which returns the final rendition of the text to be sent\nto the LLM.\n\n### Chat session in `CedarML` format:\n\n(see [CedarML](https://github.com/CedarVerse/cedarml?tab=readme-ov-file#readme) for more info)\n\n```xml\n<cedarml:tool-in.aider>\n/add aider/coders/base_coder.py\n</cedarml:tool-in.aider>\n\n<cedarml:tool-out.aider>\nAdded /GitHub/aider/aider/coders/base_coder.py to the chat\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\naider/coders/base_coder.py\n</cedarml:tool-out.aider>\n\n<cedarml:tool-in.cedartl>\nwhat does this file do? \\l0\n</cedarml:tool-in.cedartl>\n\n<cedarml:tool-out.cedartl>\n\\l0: \\rar\\sbs\n\\rar: Rephrase my request, then respond.\n\\sbs: Do so by thinking step by step.\n</cedarml:tool-out.cedartl>\n\n<cedarml:role.user>\nwhat does this file do? Rephrase my request, then respond.\nDo so by thinking step by step.\n</cedarml:role.user>\n\n<cedarml:role.assistant>\nSure, let's break down your request and then respond step by step.\n\nRephrased Request:\n\"Can you explain the purpose and main functionalities of the aider/coders/base_coder.py file?\"\n\nStep-by-Step Response:\n\n1. File Overview:\n\u2022 The aider/coders/base_coder.py file is a Python module that defines the Coder class and related functionalities.\n\u2022 This class is a core component of the Aider application, which is designed to assist users in coding tasks using AI.\n</cedarml:role.assistant>\n```\n\n<details>\n<summary>Actual chat session screenshot</summary>\n\n![img.png](img.png)\n</details>\n\n## What's Next?\n\nHere's what's on the horizon for `CedarTL`:\n\n- **Browser Extension**\n - Cross-platform extension for seamless template access in any web text input\n - Support for popular platforms:\n - LLM web interfaces ([Kagi Assistant](https://kagi.com/assistant), ChatGPT, Claude, OpenRouter, etc.)\n - Messaging apps (WhatsApp Web, Google Chat)\n - Online text editors\n - Social media platforms like Facebook, Instagram\n - Features:\n - Local template storage and management\n - Secure sync across devices\n - Template preview on hover\n - Context-aware template auto-complete\n - Integration with browser's autofill system\n - Smart template generation from frequently typed text\n\n- **Core Enhancements**\n - Template sharing ecosystem\n - More backend storage options (databases, cloud storage)\n - Better template versioning\n\n- **Integration APIs**\n - SDK for easy integration into other applications\n\n\n## Contributing\nWant to contribute? Check out our [GitHub issues](https://github.com/YourRepo/CedarTL/issues) or propose new features!\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A lightweight, intuitive templating language designed for interactive use in LLM chat sessions.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/CedarVerse/cedartl/issues",
"Change Log": "https://github.com/CedarVerse/cedartl/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/CedarVerse/cedartl#readme",
"Homepage": "https://github.com/CedarVerse/cedartl",
"Repository": "https://github.com/CedarVerse/cedartl.git"
},
"split_keywords": [
"llm",
" templating",
" productivity",
" ai-development",
" code-generation",
" prompt-engineering",
" prompt-management",
" language-processing",
" development-tools"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d6dec735f56810f2a5dd94af73804a8c975fba72cb4f7056dd692a3505efbee",
"md5": "e8a121a003402c2ff9f7c765efc92a80",
"sha256": "f1455e78dd30d50ac877e9f70077281f7f4c2a2d9f4667b2dab3b5776c677fbd"
},
"downloads": -1,
"filename": "cedartl-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8a121a003402c2ff9f7c765efc92a80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11067,
"upload_time": "2024-12-09T15:56:35",
"upload_time_iso_8601": "2024-12-09T15:56:35.861745Z",
"url": "https://files.pythonhosted.org/packages/4d/6d/ec735f56810f2a5dd94af73804a8c975fba72cb4f7056dd692a3505efbee/cedartl-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cdf56d7728b0ebbc8a2a8942c46a85048aabec25d83c1735e862feeaa05517f9",
"md5": "3c67d4db27022d6c15491690144f3816",
"sha256": "a5c58a9764e2854b834749012a4f98fd683cf09ca1a45cf953a72a2b5e5630ef"
},
"downloads": -1,
"filename": "cedartl-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3c67d4db27022d6c15491690144f3816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 376670,
"upload_time": "2024-12-09T15:56:37",
"upload_time_iso_8601": "2024-12-09T15:56:37.241422Z",
"url": "https://files.pythonhosted.org/packages/cd/f5/6d7728b0ebbc8a2a8942c46a85048aabec25d83c1735e862feeaa05517f9/cedartl-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 15:56:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CedarVerse",
"github_project": "cedartl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cedartl"
}