pipeworks_mud_mapper.services.template_service
==============================================

.. py:module:: pipeworks_mud_mapper.services.template_service

.. autoapi-nested-parse::

   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...

   .. seealso:: :py:obj:`-`, :py:obj:`-`, :py:obj:`-`



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.services.template_service.get_templates_directory
   pipeworks_mud_mapper.services.template_service.list_templates
   pipeworks_mud_mapper.services.template_service.load_template
   pipeworks_mud_mapper.services.template_service.compile_system_prompt


Module Contents
---------------

.. py:function:: get_templates_directory()

   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.
   :rtype: :py:class:`Path`

   .. admonition:: Examples

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


.. py:function:: list_templates()

   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.
   :rtype: :py:class:`list[dict]`

   .. admonition:: Examples

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


.. py:function:: load_template(template_id)

   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.

   :param template_id: The template identifier (e.g., "ledgerfall_goblin").
   :type template_id: :py:class:`str`

   :returns: The validated template, or None if not found or invalid.
   :rtype: :py:class:`OllamaTemplate | None`

   .. admonition:: Examples

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


.. py:function:: compile_system_prompt(template, target_words = 300)

   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.

   :param template: The template to compile.
   :type template: :py:class:`OllamaTemplate`
   :param target_words: 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.
   :type target_words: :py:class:`int`, *optional*

   :returns: The compiled system prompt string.
   :rtype: :py:class:`str`

   .. admonition:: 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