LLTSharp 1.6.0

LLTSharp

A flexible and expressive template engine for Large Language Model (LLM) prompts and structured message generation in C#.
LLT is designed to make prompt engineering and content generation as powerful and maintainable as regular C# code.

✨ Key Features

• Razor-inspired DSL with @if, @foreach, expressions, metadata, and inline variables
• Full expression evaluator — arithmetic, logic, ternary, null-coalescing (??), property checks (?:), safe navigation (?.), array/object literals, and method calls
• Message-oriented syntax for LLM role structures (system, user, assistant, tool)
• Powerful metadata filtering — select the best template by language, model, or custom qualifiers
• Metadata fallback schemes — hierarchical language fallback (en-US → en → sibling → default)
• Composable templates — reuse and render nested templates inside others, with optional context override (@render 'name' with ctx)
• Extensible function system — built-in functions plus custom ones registered from C#
• Deterministic formatting — indentation is normalized during parsing, inner spacing is preserved, output is predictable
• Library-driven workflow — import templates from assemblies, files, or strings
• Body parsing — parse template bodies without the @template wrapper via ParseTextTemplate / ParseMessagesTemplate

📦 Installation

Install the package from NuGet:

dotnet add package LLTSharp

Or via the Package Manager Console:

Install-Package LLTSharp

💡 Example

var parser = new LLTParser();

var templateStr = """
@template GreetingTemplate
{
    Greetings, @name!
    @if age > 18
    {
        You are an adult.
    }
    else
    {
        You are too young!
    }

    Have a nice day.
}
""";

var template = parser.Parse(templateStr).First();

var adult = new { name = "Andrew", age = 20 };
var young = new { name = "Alice", age = 15 };

Console.WriteLine(template.Render(adult));
Console.WriteLine(template.Render(young));

Output:

Greetings, Andrew!
You are an adult.

Have a nice day.

Greetings, Alice!
You are too young!

Have a nice day.

🧩 Template Library Usage

Multiple templates can be stored, versioned, and retrieved by language or model ID:

var lib = new TemplateLibrary();

lib.ImportFromString("""
@template greeting
{
    @metadata { lang: 'en' }
    Hello!
}

@template greeting
{
    @metadata { lang: 'en', model: 'gpt-4' }
    Hello GPT-4!
}

@template greeting
{
    @metadata { lang: 'es' }
    Hola!
}
""");

var template = lib.Retrieve("greeting", new LanguageMetadata("en"), new TargetModelMetadata("gpt-4"));
Console.WriteLine(template.Render()); // Hello GPT-4!

Templates are resolved by metadata specificity, similar to CSS selector priority. If no template matches exactly, use fallback retrieval:

// en-US → en → any sibling of the same language root → default language
lib.SetLanguageFallbackScheme(new HierarchicalLanguageFallbackScheme("en"));

var fallback = lib.RetrieveWithFallback("greeting", new LanguageMetadata("en-US"));

💬 Message Templates for LLM Chats

LLT supports special @messages syntax for structured chat prompts:

@messages template ChatBot
{
    @metadata { language: 'en', version: 1 }

    @system message {
        You are a helpful assistant.

        Here is your instructions:
        @foreach instruction in instructions {
            Instruction: @instruction
        }
    }

    @foreach name in names {
        @message {
            @role 'user'
            Hello, I am @name!
        }
    }
}

Rendered result: a sequence of chat messages with proper roles (system, user, assistant, tool). Roles can be declared statically (@system message, @user message, @assistant message, @tool message) or dynamically via @message { @role <expression> ... }.

🧠 Language Reference

Expressions

Literals

Access

Unary operators

Binary operators (by precedence, high → low)

Null-coalescing, Has and Safe navigation

@template t {
    1: @(?value ?? 'No value')
    2: @(ctx ?: 'value' ? value ?? 'Null' : 'No value')
}

• ?? treats missing and null the same way.
• ?: (has) distinguishes them: it only checks existence, so it works great as the condition when you need different fallbacks for null vs. missing:

@(user ?: 'name' ? user.name : 'Anonymous')
@(user?.name ?? 'Anonymous')        @/ Safe navigation + coalescing

Formatting

An expression can be followed by : and a format string:

Price: @price:'0.00'

Statements

Comments are skipped by the parser and can be placed wherever whitespace is allowed, including inside template bodies.

Escapes: @@ renders a literal @, {{ renders {, }} renders }.

Multi-line raw text can be wrapped in five backticks to avoid escaping:

@template code_sample
{
    `````
    @if isNotParsed { this is raw text, not a statement }
    `````
}

Metadata

Attach metadata to a template with the @metadata block (only constant values are allowed):

@template greeting
{
    @metadata { lang: 'en', model: 'gpt-4', version: 2 }
    Hello!
}

Built-in metadata keys (parsed by the corresponding factories):

Pass factories to Parse so the keys are recognized; unknown keys become AdditionalMetadata:

var parser = new LLTParser();
var templates = parser.Parse(src, new MetadataFactory[]
{
    new LanguageMetadataFactory(),
    new TargetModelMetadataFactory(),
    new VersionMetadataFactory(),
});

Custom metadata

public class MyMetadata : IMetadata
{
    public MyMetadata(string value) => Value = value;
    public string Value { get; }
}

public class MyMetadataFactory : MetadataFactory
{
    public override bool TryCreateMetadata(string key, TemplateDataAccessor value, out IMetadata metadata)
    {
        if (key == "my_key")
        {
            metadata = new MyMetadata(value.ToString());
            return true;
        }
        metadata = null;
        return false;
    }
}

Fallback schemes

• lib.SetLanguageFallbackScheme(new HierarchicalLanguageFallbackScheme("en")) — walks up the language hierarchy (en-US → en), then tries siblings, then the default language.
• lib.SetLanguageFallbackScheme(new MajorLanguageFallbackScheme()) — falls back to the major language group.
• lib.SetFallbackScheme(typeof(LanguageMetadata), scheme) — register a custom MetadataFallbackScheme<T> for any metadata type.

Retrieval API: Retrieve, TryRetrieve, TryRetrieveBest, RetrieveWithFallback, RetrieveAll — each with optional identifier and metadata arguments.

🔧 Functions

Built-in functions (TemplateFunctions.All):

Register custom functions and pass them to Render:

var functions = new TemplateFunctionSet(includeDefault: true,
    new TemplateFunction("shout", (self, args) => args[0].ToString().ToUpperInvariant()));

var rendered = template.Render(new { name = "Andrew" }, functions);

Hello, @shout(name)!   @/ → Hello, ANDREW!

🧾 Formatting & Scoping Rules

• Leading indentation is normalized during parsing: every line loses up to depth × TabSize leading whitespace, where depth is the block nesting level. You can write templates with comfortable indentation — the common base indent is stripped and the output stays clean
• Inner whitespace, line breaks and blank lines are preserved as written
• Leading/trailing blank lines of blocks are trimmed; indentation before complex statements (@if, @foreach, @while) is removed
• Lines containing only non-rendering constructs — @/ and @* *@ comments, @let declarations, variable assignments — are removed entirely: the surrounding line breaks are trimmed so they leave no blank lines in the output
• TabSize (default 4) on LLTParser controls how many columns one indent level takes during refinement
• @let variables are lexically scoped
• Loop variables do not leak outside their block
• Nested @if and @foreach blocks behave predictably, matching C#‑like logical semantics

🏗️ Architecture Overview

• LLTParser – parses source text into ASTs (TemplateNode, TemplateExpressionNode, etc.); supports full-file parsing (Parse) and body-only parsing (ParseTextTemplate, ParseMessagesTemplate)
• Template – runtime object capable of rendering with dynamic context (TextTemplate, MessagesTemplate)
• TemplateLibrary – registry and loader for collections of templates with filtering and fallbacks
• Metadata System – extensible mechanism for attaching attributes such as language, model, or custom version
• Data Accessors – reflection / dictionary / array wrappers (DataAccessorFactory) with PropertiesToLowerCase, KeysToLowerCase and Snapshot options
• Function System – TemplateFunctionSet / TemplateFunction for extending template logic
• ChatMessage Model – unified representation for structured message templates (system, user, assistant, tool)

🔖 License

MIT License © 2025