pipeworks_mud_mapper.services.template_service

Ollama template service for loading and compiling prompt templates.

This module provides functions for working with Ollama templates - JSON files that encode theme, voice, and constraint guidance for LLM room descriptions.

Template Operations

get_templates_directory(): Get the templates directory path
list_templates(): List available templates for dropdown population
load_template(): Load and validate a single template
compile_system_prompt(): Convert template to system prompt string

Template Location

Templates are stored in data/ollama/templates/ as JSON files with the .template.json extension. The directory is created automatically if missing.

Usage

List available templates:

>>> from pipeworks_mud_mapper.services import template_service
>>> templates = template_service.list_templates()
>>> print(templates)
[{'label': 'Ledgerfall Goblin', 'value': 'ledgerfall_goblin'}, ...]

Load and compile a template:

>>> template = template_service.load_template("ledgerfall_goblin")
>>> system_prompt = template_service.compile_system_prompt(template)
>>> print(system_prompt[:100])
You are a Game Master describing a single room...

Functions

`get_templates_directory`()	Get the templates directory path.
`list_templates`()	List available templates for dropdown population.
`load_template`(template_id)	Load and validate a template by its ID.
`compile_system_prompt`(template[, target_words])	Compile a template into a system prompt string.

Module Contents

pipeworks_mud_mapper.services.template_service.get_templates_directory()[source]

Get the templates directory path.

Returns the path to data/ollama/templates/ relative to the project root. Creates the directory if it doesn’t exist.

Returns:: Absolute path to the templates directory.
Return type:: Path

Examples

>>> templates_dir = get_templates_directory()
>>> print(templates_dir)
/path/to/project/data/ollama/templates

pipeworks_mud_mapper.services.template_service.list_templates()[source]

List available templates for dropdown population.

Scans the templates directory for .template.json files and returns a list suitable for Dash dropdown options.

Returns:: List of dicts with ‘label’ (display name) and ‘value’ (template_id). Sorted alphabetically by label.
Return type:: list[dict]

Examples

>>> templates = list_templates()
>>> print(templates)
[{'label': 'Ledgerfall Goblin', 'value': 'ledgerfall_goblin'}]

pipeworks_mud_mapper.services.template_service.load_template(template_id)[source]

Load and validate a template by its ID.

Searches for a template file with matching template_id in the templates directory and validates it against the Pydantic model.

Parameters:: template_id (str) – The template identifier (e.g., “ledgerfall_goblin”).
Returns:: The validated template, or None if not found or invalid.
Return type:: OllamaTemplate | None

Examples

>>> template = load_template("ledgerfall_goblin")
>>> if template:
...     print(template.template_name)
Ledgerfall Goblin

pipeworks_mud_mapper.services.template_service.compile_system_prompt(template, target_words=300)[source]

Compile a template into a system prompt string.

Combines the universal Core Rules with theme-specific guidance, voice settings, craft constraints, and examples to produce a comprehensive system prompt for the LLM.

Parameters:

template (OllamaTemplate) – The template to compile.
target_words (int, optional) – Target word count for the generated description. The compiled prompt will include a range (approximately 67%-117% of target) to give the LLM flexibility. Default is 300.

Returns:

The compiled system prompt string.

Return type:

str

Examples

>>> template = load_template("ledgerfall_goblin")
>>> prompt = compile_system_prompt(template)
>>> print(prompt[:50])
You are a Game Master describing a single room...

>>> # With custom word count
>>> prompt = compile_system_prompt(template, target_words=150)
>>> "100-175 words" in prompt
True