pipeworks_mud_mapper.models.template

Ollama template models for LLM prompt generation.

This module defines Pydantic models for Ollama templates that encode theme, voice guidance, and craft constraints for generating room descriptions.

Template Structure

Templates follow the Craft of Constraint philosophy and compile into comprehensive system prompts for small LLMs like Gemma2:2B.

OllamaTemplate
├── template_name, template_id, version
├── description
├── theme: TemplateTheme
│   ├── name (thematic world)
│   ├── tone (emotional register)
│   ├── era (time period)
│   └── aesthetic (sensory flavor)
├── voice_guidance: TemplateVoiceGuidance
│   ├── style (how the GM speaks)
│   ├── register (formality level)
│   ├── keyword_include (words to weave in)
│   └── keyword_exclude (words to avoid)
├── craft_constraints: TemplateCraftConstraints
│   ├── multi_part_spaces
│   ├── locked_things_approach
│   ├── silence_tone
│   └── exit_hints
├── examples: TemplateExamples
│   ├── good_crossroads / bad_crossroads
│   ├── good_locked_thing / bad_locked_thing
│   └── good_multi_part / bad_multi_part
├── author_notes
└── author_credit

Usage

Load and validate a template:

from pipeworks_mud_mapper.models import OllamaTemplate
import json

with open("template.json") as f:
    data = json.load(f)
template = OllamaTemplate.model_validate(data)

Classes

`TemplateTheme`	Theme configuration for an Ollama template.
`TemplateVoiceGuidance`	Voice and style guidance for an Ollama template.
`TemplateCraftConstraints`	Craft of Constraint specific guidance for an Ollama template.
`TemplateExamples`	Good and bad examples for an Ollama template.
`OllamaTemplate`	A complete Ollama template for room description generation.

Module Contents

class pipeworks_mud_mapper.models.template.TemplateTheme(/, **data)[source]

Bases: pydantic.BaseModel

Theme configuration for an Ollama template.

Defines the thematic world, emotional register, time period, and sensory flavor for room descriptions.

name

The thematic world (e.g., “Ledgerfall, a goblin-run urban realm”).

Type:: str

tone

Primary emotional register (e.g., “whimsical, deadpan, slightly chaotic”).

Type:: str

era

Time period if relevant (e.g., “Victorian-inspired”). Can be empty.

Type:: str

aesthetic

Visual/sensory flavor (e.g., “copper pipes, ink smudges, rust”).

Type:: str

class pipeworks_mud_mapper.models.template.TemplateVoiceGuidance(/, **data)[source]

Bases: pydantic.BaseModel

Voice and style guidance for an Ollama template.

Defines how the Game Master “speaks” in room descriptions, including formality, style, and keyword guidance.

style

How the GM speaks (e.g., “as if narrating for a gossip column”).

Type:: str

voice_register

Formality level (e.g., “matter-of-fact with dry humor”). Note: Named voice_register to avoid shadowing Pydantic’s register method.

Type:: str

keyword_include

Words/concepts to weave in when fitting.

Type:: list[str]

keyword_exclude

Words/concepts to avoid.

Type:: list[str]

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pipeworks_mud_mapper.models.template.TemplateCraftConstraints(/, **data)[source]

Bases: pydantic.BaseModel

Craft of Constraint specific guidance for an Ollama template.

Provides theme-specific guidance for common description challenges: multi-part spaces, locked things, silence, and exit descriptions.

multi_part_spaces

How to describe wide/complex spaces (markets, long streets).

Type:: str

locked_things_approach

How to handle barriers without explaining solutions.

Type:: str

silence_tone

What silence feels like in this theme.

Type:: str

exit_hints

How to describe directions without narrating destinations.

Type:: str

class pipeworks_mud_mapper.models.template.TemplateExamples(/, **data)[source]

Bases: pydantic.BaseModel

Good and bad examples for an Ollama template.

Provides concrete examples that guide small LLMs to produce correct descriptions by showing what TO do and what NOT to do.

good_crossroads

Correct way to describe a choice point.

Type:: str

bad_crossroads

Common mistake when describing choice points.

Type:: str

good_locked_thing

Correct way to describe barriers without explaining solutions.

Type:: str

bad_locked_thing

Common mistake when describing barriers.

Type:: str

good_multi_part

Correct way to describe the middle of a complex space.

Type:: str

bad_multi_part

Common mistake with wide/complex spaces.

Type:: str

class pipeworks_mud_mapper.models.template.OllamaTemplate(/, **data)[source]

Bases: pydantic.BaseModel

A complete Ollama template for room description generation.

Templates compile into comprehensive system prompts that guide small LLMs (like Gemma2:2B) to produce consistent, constraint-respecting room descriptions following the Craft of Constraint philosophy.

template_name

Human-readable display name (e.g., “Ledgerfall Goblin”).

Type:: str

template_id

Unique identifier in slug format (e.g., “ledgerfall_goblin”).

Type:: str

version

Semantic version (default: “1.0.0”).

Type:: str

description

Brief explanation of when/why to use this template.

Type:: str

theme

Thematic world configuration.

Type:: TemplateTheme

voice_guidance

Voice and style guidance.

Type:: TemplateVoiceGuidance

craft_constraints

Craft of Constraint specific guidance.

Type:: TemplateCraftConstraints

examples

Good and bad examples for the template.

Type:: TemplateExamples

author_notes

Meta guidance for template authors/forkers.

Type:: str

author_credit

Template creator attribution.

Type:: str

Examples

Create a minimal template:

>>> template = OllamaTemplate(
...     template_name="My Theme",
...     template_id="my_theme",
...     theme=TemplateTheme(name="A fantasy world", tone="epic"),
...     voice_guidance=TemplateVoiceGuidance(
...         style="grand narrator",
...         register="formal"
...     ),
... )

Load from JSON file:

>>> import json
>>> with open("template.json") as f:
...     data = json.load(f)
>>> template = OllamaTemplate.model_validate(data)