pipeworks_mud_mapper.services.ollama_state
==========================================

.. py:module:: pipeworks_mud_mapper.services.ollama_state

.. autoapi-nested-parse::

   State helpers for applying Ollama outputs to map data.

   This module centralizes the domain logic for:
   - building generation metadata
   - applying generated descriptions to rooms
   - attaching or clearing validation metadata

   Keeping these operations here allows callbacks to remain thin and
   makes unit testing easier.



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.services.ollama_state.build_generation_metadata
   pipeworks_mud_mapper.services.ollama_state.apply_generation_to_room


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

.. py:function:: build_generation_metadata(*, model, actual_seed, template_id, temperature, top_k, top_p, num_ctx, num_predict, target_words, system_prompt, user_prompt, generated_at = None)

   Build a metadata dictionary matching OllamaGenerationInfo fields.

   :param model: Ollama model identifier used for generation.
   :type model: :py:class:`str`
   :param actual_seed: Seed that was actually used (>= 0).
   :type actual_seed: :py:class:`int`
   :param template_id: Template ID used for generation.
   :type template_id: :py:class:`str`
   :param temperature: Temperature parameter used for generation.
   :type temperature: :py:class:`float`
   :param top_k: Top-K sampling parameter.
   :type top_k: :py:class:`int`
   :param top_p: Top-P sampling parameter.
   :type top_p: :py:class:`float`
   :param num_ctx: Context window size used for generation.
   :type num_ctx: :py:class:`int`
   :param num_predict: Maximum output tokens requested.
   :type num_predict: :py:class:`int`
   :param target_words: Target word count used in the system prompt.
   :type target_words: :py:class:`int`
   :param system_prompt: Full system prompt (compiled or custom).
   :type system_prompt: :py:class:`str | None`
   :param user_prompt: User prompt entered by the author.
   :type user_prompt: :py:class:`str`
   :param generated_at: Optional ISO timestamp; if None, uses current UTC.
   :type generated_at: :py:class:`str | None`

   :returns: Metadata dictionary for storage in map files.
   :rtype: :py:class:`dict[str`, :py:class:`Any]`


.. py:function:: apply_generation_to_room(*, zone_data, room_id, description, generation_info, validation_info)

   Return updated zone data with the generated description applied.

   :param zone_data: Current zone data object.
   :type zone_data: :py:class:`dict`
   :param room_id: Room ID to update.
   :type room_id: :py:class:`str`
   :param description: Generated description text to apply.
   :type description: :py:class:`str`
   :param generation_info: Metadata about the LLM generation; when None, metadata is cleared.
   :type generation_info: :py:class:`dict[str`, :py:class:`Any] | None`
   :param validation_info: Validator metadata to attach; when None, validation info is cleared.
   :type validation_info: :py:class:`dict[str`, :py:class:`Any] | None`

   :returns: Updated zone data with modified room data.
   :rtype: :py:class:`dict`

   :raises KeyError: If room_id is not in the zone data.