dotprompt 2.0.0

Dotprompt for Dart: parse and render .prompt files (YAML frontmatter + Handlebars templates) for Generative AI.

Dotprompt for Dart

Dart implementation of Dotprompt, an executable prompt template file format for Generative AI.

Overview

Dotprompt provides a structured way to create, manage, and render prompt templates for Large Language Models. This Dart implementation offers:

• YAML frontmatter for configuration and metadata
• Handlebars-style templating for dynamic content
• Picoschema support for input/output validation
• Tool and schema resolution for complex workflows
• Cross-runtime conformance with JavaScript, Python, Go, Rust, and Java

Installation

Add to your pubspec.yaml:

dependencies:
  dotprompt: ^2.0.0

Quick Start

import 'package:dotprompt/dotprompt.dart';

void main() async {
  final dotprompt = Dotprompt();
  
  // Parse and render a prompt
  final result = await dotprompt.render('''
---
model: googleai/gemini-flash-latest
config:
  temperature: 0.7
---
Hello {{name}}! You are a {{role}}.
''', DataArgument(
    input: {'name': 'World', 'role': 'helpful assistant'},
  ));
  
  print(result.messages.first.content);
  // Output: [TextPart(text: "Hello World! You are a helpful assistant.")]
}

Features

Template Parsing

final parsed = dotprompt.parse('''
---
model: googleai/gemini-flash-latest
input:
  schema:
    name: string
    age?: integer
  default:
    name: User
---
Hello {{name}}!
''');

print(parsed.model);  // "googleai/gemini-flash-latest"
print(parsed.input?.schema);  // Schema definition

Compiled Templates

For repeated rendering with different data:

final compiled = await dotprompt.compile(templateSource);

// Render multiple times
final result1 = await compiled.render(DataArgument(input: {'name': 'Alice'}));
final result2 = await compiled.render(DataArgument(input: {'name': 'Bob'}));

Partials

final dotprompt = Dotprompt(DotpromptOptions(
  partials: {
    'header': 'Welcome, {{user}}!',
    'footer': 'Best regards, {{sender}}',
  },
));

final result = await dotprompt.render('''
{{> header}}
Your message here.
{{> footer}}
''', DataArgument(
    input: {'user': 'Alice', 'sender': 'Bot'},
  ));

Role Markers

Control message roles in multi-turn conversations:

final result = await dotprompt.render('''
{{role "system"}}
You are a helpful assistant.

{{role "user"}}
Hello!

{{role "model"}}
Hi there! How can I help?
''', DataArgument());

// Results in 3 messages with appropriate roles

Media Embedding

final result = await dotprompt.render('''
Please analyze this image:
{{media url="https://example.com/image.png" contentType="image/png"}}
''', DataArgument());

Picoschema

input.schema and output.schema accept Picoschema and are converted to JSON Schema by renderMetadata/render:

output:
  schema:
    title: string, the article title
    subtitle?: string
    tags(array, relevant tags): string
    status(enum): [DRAFT, PUBLISHED]
    author: Author        # named schema
    labels(object):
      (*): string         # additionalProperties

Named schemas are JSON Schema, registered up front or resolved on demand:

final dotprompt = Dotprompt(DotpromptOptions(
  schemas: {'Author': authorJsonSchema},
  schemaResolver: (name) async => lookupJsonSchema(name),
));

// Or convert directly.
final jsonSchema = await Picoschema.parse(
  {'author': 'Author', 'tags(array)': 'string'},
  schemaResolver: (name) async => lookupJsonSchema(name),
);

A schema that is already JSON Schema is passed through as-is. As in the other runtimes, that means a top-level type naming a JSON Schema type or a properties map (plus anyOf/oneOf/allOf/enum lists, $schema and $ref):

output:
  schema:
    type: object
    properties:
      title: {type: string}

Upgrading from 1.x? Picoschema is now strict (string[], a | b and free-text parentheses throw). See the CHANGELOG.

API Reference

Core Classes

Class	Description
Dotprompt	Main entry point for parsing and rendering
ParsedPrompt	Result of parsing a template
RenderedPrompt	Result of rendering with data
Message	A chat message with role and content
Part	Message content (TextPart, MediaPart, etc.)

Configuration

final dotprompt = Dotprompt(DotpromptOptions(
  defaultModel: 'googleai/gemini-flash-latest',
  modelConfigs: {
    'googleai/gemini-flash-latest': {'temperature': 0.7},
  },
  partials: {'...': '...'},
  tools: {'...': ToolDefinition(...)},
  schemas: {'...': {...}},
  partialResolver: (name) async => '...',
  toolResolver: (name) async => {...},
  schemaResolver: (name) async => {...},
));

Built-in Helpers

Helper	Usage	Description
role	{{role "system"}}	Sets message role
media	{{media url="..." contentType="..."}}	Embeds media
history	{{history}}	Inserts conversation history
json	{{json data}}	JSON serialization
section	{{#section "name"}}...{{/section}}	Named sections
ifEquals	{{#ifEquals a b}}...{{/ifEquals}}	Conditional
unlessEquals	{{#unlessEquals a b}}...{{/unlessEquals}}	Inverse conditional

Building with Bazel

This package is built using rules_dart:

# Build the library
bazel build //dart/dotprompt

# Run tests
bazel test //dart/dotprompt/test:...

License

Apache 2.0 - See LICENSE for details.