Overview

Relevant source files

This document provides an introduction to the Dotprompt repository, explaining its purpose as a language-neutral executable prompt template format for Generative AI applications. It covers the multi-language implementation strategy, repository organization, and how the different components work together to provide consistent prompt templating across JavaScript, Python, Go, and Java ecosystems.

For detailed information about the Dotprompt format itself, see What is Dotprompt. For language-specific implementation details, see sections JavaScript Implementation, Python Implementation, Go Implementation, and Java Implementation.

What is Dotprompt

Dotprompt is an executable prompt template file format for Generative AI that combines three key elements:

YAML frontmatter containing metadata (model configuration, input/output schemas, tools)
Handlebars templates for dynamic content generation
Picoschema for simplified schema definitions

The format is designed to be language-agnostic, allowing prompt templates to be shared and reused across different programming languages and model providers. A .prompt file encapsulates all the information needed to execute a prompt, including model configuration, input validation, output formatting, and the template itself.

README.md11-15 defines Dotprompt as "an executable prompt template file format for Generative AI" that "is designed to be agnostic to programming language and model provider" and "extends the popular Handlebars templating language with GenAI-specific features."

Sources: README.md9-47

Multi-Language Implementation Architecture

The repository implements Dotprompt in four programming languages, each providing identical functionality while optimized for their respective ecosystems. The implementations share a common specification defined through YAML test files, ensuring consistent behavior across all languages.

Diagram: Language Implementations and Shared Specification

Each implementation provides:

A Dotprompt class/struct for parsing and rendering templates
Picoschema-to-JSON Schema conversion
Built-in Handlebars helpers (role, history, json, section, media)
Resolver interfaces for tools, schemas, and partials
Message and Part type hierarchies for structured output

The .release-please-config.json14-94 file configures independent releases for each package: js/, python/dotpromptz/, python/handlebarrz/, go/, and java/.

Sources: README.md9-15 .release-please-config.json14-94 Diagram 1 from provided context

Repository Structure

The repository is organized as a monorepo containing independent implementations alongside shared resources:

Diagram: Repository Directory Structure

Each language directory contains:

Source code implementing the Dotprompt API
Language-specific build configuration
Tests that validate against the shared spec files
Package metadata (package.json, pyproject.toml, go.mod, BUILD.bazel)

The spec/ directory contains YAML files defining test cases that all implementations must pass, ensuring behavioral consistency. Example files include spec/basic.yaml, spec/helpers/role.yaml, and others.

Sources: .release-please-config.json14-94 docs/contributing/releases.md9-18

Core Processing Pipeline

All implementations follow the same five-phase pipeline to transform .prompt files into structured output:

Diagram: Template Processing Pipeline (Language-Agnostic)

The pipeline components:

Phase 1 (Parsing): Extracts YAML frontmatter and template body, converts Picoschema to JSON Schema
Phase 2 (Resolution): Loads external resources (tools, schemas, partials) using resolver interfaces
Phase 3 (Compilation): Registers custom Handlebars helpers and compiles the template into executable form
Phase 4 (Rendering): Executes the compiled template with runtime data, where helpers emit marker strings like <<<dotprompt:role:user>>>
Phase 5 (Message Construction): Parses marker strings to create structured Message objects with typed Part content

This separation allows templates to be compiled once and rendered multiple times with different data.

Sources: Diagram 4 from provided context, README.md17-47

Package Versions and Release Management

The repository uses release-please for automated version management and CHANGELOG generation based on Conventional Commits. Each language package is released independently:

Package	Current Version	Registry	Scope
`dotprompt` (JS)	1.1.1	npm	`js`
`dotpromptz` (Python)	0.1.4	PyPI	`py/dotpromptz`
`handlebarrz` (Python)	0.1.3	PyPI	`py/handlebarrz`
`dotprompt-go`	0.1.0	pkg.go.dev	`go`
`dotprompt-java`	0.1.0	Maven Central	`java`

The .release-please-config.json1-97 configures release-please with "separate-pull-requests": true and "include-component-in-tag": true, enabling independent releases. Each package has its own:

Version tracking in .release-please-manifest.json
CHANGELOG.md file
Release tags (e.g., dotprompt-1.1.1, dotpromptz-0.1.4)

The .github/workflows/release-please.yml1-83 workflow automates releases by:

Analyzing conventional commits to determine version bumps
Creating/updating release PRs with version changes and CHANGELOGs
Triggering package publishing when release PRs are merged
Updating python/uv.lock for Python packages

Commit message format follows Conventional Commits:

<type>(<scope>): <description>

Examples:
feat(js): add new template helper
fix(py/dotpromptz): resolve parsing issue
docs(go): update API documentation

The .github/release-please.yml27-48 defines valid types (feat, fix, docs, etc.) and scopes (js, py, go, java, deps).

Sources: .release-please-config.json1-97 .github/workflows/release-please.yml1-83 docs/contributing/releases.md1-106 .github/release-please.yml17-48

Specification-Driven Testing

Cross-language consistency is ensured through a shared YAML specification test suite located in spec/*.yaml. Each implementation dynamically generates unit tests from these YAML files, validating four critical capabilities:

Diagram: Spec-Based Cross-Language Testing

Each YAML spec file defines:

template: The .prompt file content to test
data: Input data for rendering
schemas, tools, partials: External resources to register
tests[]: Array of test cases with expected output

This architecture ensures that a prompt written for one implementation will behave identically in another, enabling teams to migrate between languages or share prompts across services.

Sources: Diagram 2 from provided context

Build Infrastructure

The monorepo uses multiple build systems optimized for each language:

Language	Build System	Package Manager	Config Files
JavaScript	tsup, tsc	pnpm	package.json, pnpm-lock.yaml
Python	hatchling, maturin	uv	pyproject.toml, uv.lock
Go	go build	go modules	go.mod, go.sum
Java	Bazel	Maven	BUILD.bazel, MODULE.bazel.lock

The scripts/ directory provides orchestration scripts:

scripts/setup: Environment provisioning and tool installation
scripts/fmt: Code formatting across all languages
scripts/run_tests: Execute test suites for all implementations
scripts/update_deps: Dependency management

Quality gates are enforced through Git hooks configured in captainhook.json:

commit-msg: Validates conventional commit format
pre-commit: Runs formatters, linters, tests, and builds
pre-push: Full validation suite and branch policy enforcement

CI/CD pipelines in .github/workflows/ provide additional validation:

python.yml: Multi-version testing (Python 3.10-3.14, PyPy)
test.yml: JavaScript testing with Vitest
go.yml: Go testing and linting
java.yml: Bazel build and testing

Sources: Diagram 3 from provided context, .github/workflows/release-please.yml1-83

Getting Started

To use Dotprompt in your project, choose your language and follow the installation instructions:

JavaScript (npm)

Python (PyPI)

Go

Java (Maven)

For comprehensive getting started guides, including example code and integration patterns, see Getting Started. For detailed API documentation, see language-specific sections: JavaScript, Python, Go, or Java.

The README.md87-143 provides a complete example using the Firebase Genkit SDK (which includes a Dotprompt implementation), demonstrating how to load and execute a .prompt file.

Sources: README.md87-143 java/README.md1-112