pipeworks_mud_mapper.models.template ==================================== .. py:module:: pipeworks_mud_mapper.models.template .. autoapi-nested-parse:: 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) .. seealso:: :py:obj:`-`, :py:obj:`-` Classes ------- .. autoapisummary:: pipeworks_mud_mapper.models.template.TemplateTheme pipeworks_mud_mapper.models.template.TemplateVoiceGuidance pipeworks_mud_mapper.models.template.TemplateCraftConstraints pipeworks_mud_mapper.models.template.TemplateExamples pipeworks_mud_mapper.models.template.OllamaTemplate Module Contents --------------- .. py:class:: TemplateTheme(/, **data) Bases: :py:obj:`pydantic.BaseModel` Theme configuration for an Ollama template. Defines the thematic world, emotional register, time period, and sensory flavor for room descriptions. .. attribute:: name The thematic world (e.g., "Ledgerfall, a goblin-run urban realm"). :type: :py:class:`str` .. attribute:: tone Primary emotional register (e.g., "whimsical, deadpan, slightly chaotic"). :type: :py:class:`str` .. attribute:: era Time period if relevant (e.g., "Victorian-inspired"). Can be empty. :type: :py:class:`str` .. attribute:: aesthetic Visual/sensory flavor (e.g., "copper pipes, ink smudges, rust"). :type: :py:class:`str` .. py:class:: TemplateVoiceGuidance(/, **data) Bases: :py:obj:`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. .. attribute:: style How the GM speaks (e.g., "as if narrating for a gossip column"). :type: :py:class:`str` .. attribute:: voice_register Formality level (e.g., "matter-of-fact with dry humor"). Note: Named voice_register to avoid shadowing Pydantic's register method. :type: :py:class:`str` .. attribute:: keyword_include Words/concepts to weave in when fitting. :type: :py:class:`list[str]` .. attribute:: keyword_exclude Words/concepts to avoid. :type: :py:class:`list[str]` .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:class:: TemplateCraftConstraints(/, **data) Bases: :py:obj:`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. .. attribute:: multi_part_spaces How to describe wide/complex spaces (markets, long streets). :type: :py:class:`str` .. attribute:: locked_things_approach How to handle barriers without explaining solutions. :type: :py:class:`str` .. attribute:: silence_tone What silence feels like in this theme. :type: :py:class:`str` .. attribute:: exit_hints How to describe directions without narrating destinations. :type: :py:class:`str` .. py:class:: TemplateExamples(/, **data) Bases: :py:obj:`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. .. attribute:: good_crossroads Correct way to describe a choice point. :type: :py:class:`str` .. attribute:: bad_crossroads Common mistake when describing choice points. :type: :py:class:`str` .. attribute:: good_locked_thing Correct way to describe barriers without explaining solutions. :type: :py:class:`str` .. attribute:: bad_locked_thing Common mistake when describing barriers. :type: :py:class:`str` .. attribute:: good_multi_part Correct way to describe the middle of a complex space. :type: :py:class:`str` .. attribute:: bad_multi_part Common mistake with wide/complex spaces. :type: :py:class:`str` .. py:class:: OllamaTemplate(/, **data) Bases: :py:obj:`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. .. attribute:: template_name Human-readable display name (e.g., "Ledgerfall Goblin"). :type: :py:class:`str` .. attribute:: template_id Unique identifier in slug format (e.g., "ledgerfall_goblin"). :type: :py:class:`str` .. attribute:: version Semantic version (default: "1.0.0"). :type: :py:class:`str` .. attribute:: description Brief explanation of when/why to use this template. :type: :py:class:`str` .. attribute:: theme Thematic world configuration. :type: :py:class:`TemplateTheme` .. attribute:: voice_guidance Voice and style guidance. :type: :py:class:`TemplateVoiceGuidance` .. attribute:: craft_constraints Craft of Constraint specific guidance. :type: :py:class:`TemplateCraftConstraints` .. attribute:: examples Good and bad examples for the template. :type: :py:class:`TemplateExamples` .. attribute:: author_notes Meta guidance for template authors/forkers. :type: :py:class:`str` .. attribute:: author_credit Template creator attribution. :type: :py:class:`str` .. admonition:: 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)