mud_server.translation.config
=============================

.. py:module:: mud_server.translation.config

.. autoapi-nested-parse::

   Translation layer configuration.

   ``TranslationLayerConfig`` is a frozen dataclass that mirrors the
   ``translation_layer`` block inside each world's ``world.json``.  It is
   loaded once when the World is initialised and never mutated at runtime.

   Configuration precedence (locked)
   ----------------------------------
   1. If server-level ``ollama_translation.enabled = false``
      → translation is OFF globally (enforced in World._init_translation_service).
   2. Else if world.json ``translation_layer.enabled = true``
      → translation is ON for that world.
   3. Otherwise → OFF.

   World config may override individual field values (model, timeout, etc.),
   but it cannot override the server master switch.

   Deterministic mode
   ------------------
   When ``deterministic = true`` the renderer will clamp temperature to 0.0
   and use an integer seed derived from the IPC hash.

   IPC hash sourcing (FUTURE — axis engine integration)
   ----------------------------------------------------
   Currently ``translate()`` accepts an optional ``ipc_hash: str | None``
   parameter.  When it is ``None`` (the default) deterministic mode is
   skipped even if ``deterministic = true`` in config, because there is no
   seed available yet.

   Once the axis engine is built and integrated, it will call::

       ipc_hash = axis_engine.compute_ipc(world_id, entity_a, entity_b, turn)

   and pass that hash to ``service.translate(..., ipc_hash=ipc_hash)``.  At
   that point deterministic mode will activate automatically when
   ``deterministic = true`` and the hash is provided.

   See ``_working/translation_layer/ooc_ic_translator_design_principles.md``
   section 3 (Determinism Mode) for the full specification.



Classes
-------

.. autoapisummary::

   mud_server.translation.config.TranslationLayerConfig


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

.. py:class:: TranslationLayerConfig

   Immutable, world-scoped configuration for the OOC→IC translation layer.

   Loaded from the ``translation_layer`` block in a world's ``world.json``
   and frozen after construction so that no runtime code can mutate it.

   .. attribute:: enabled

      Master switch.  If ``False`` the service will
      not be instantiated and the layer is inactive.

   .. attribute:: model

      Ollama model tag (e.g. ``"gemma2:2b"``).

   .. attribute:: ollama_base_url

      Base URL of the running Ollama instance.
      The ``/api/chat`` path is appended automatically.

   .. attribute:: timeout_seconds

      HTTP request timeout for Ollama calls.  On
      expiry the service returns ``None`` and the
      caller falls back to the OOC message.

   .. attribute:: keep_alive

      Ollama ``keep_alive`` duration string.
      Controls how long the model stays loaded in
      GPU/CPU memory after each request (e.g.
      ``"5m"``).  Prevents cold-start reloads
      between consecutive requests.

   .. attribute:: strict_mode

      When ``True``, any non-compliant LLM output
      (multi-line, forbidden patterns, over-length)
      triggers an immediate fallback rather than a
      best-effort cleanup.

   .. attribute:: max_output_chars

      Hard ceiling on IC output length.  Responses
      exceeding this are rejected (strict) or
      truncated (non-strict).

   .. attribute:: prompt_policy_id

      Canonical prompt policy id selector used for
      runtime resolution (for example
      ``prompt:translation.prompts.ic:default``).

   .. attribute:: active_axes

      Subset of axis names to include in the
      character profile sent to the LLM.  An empty
      list means "all axes that exist for this
      character".

   .. attribute:: deterministic

      When ``True`` and a non-``None`` ``ipc_hash``
      is provided to ``translate()``, the renderer
      will use ``temperature=0.0`` and a seed
      derived from the IPC hash.  See module
      docstring for IPC sourcing status.


   .. py:attribute:: enabled
      :type:  bool


   .. py:attribute:: model
      :type:  str


   .. py:attribute:: ollama_base_url
      :type:  str


   .. py:attribute:: timeout_seconds
      :type:  float


   .. py:attribute:: keep_alive
      :type:  str


   .. py:attribute:: strict_mode
      :type:  bool


   .. py:attribute:: max_output_chars
      :type:  int


   .. py:attribute:: prompt_policy_id
      :type:  str | None


   .. py:attribute:: active_axes
      :type:  list[str]


   .. py:attribute:: deterministic
      :type:  bool


   .. py:property:: api_endpoint
      :type: str


      Full Ollama ``/api/chat`` URL constructed from ``ollama_base_url``.


   .. py:method:: from_dict(data, *, world_root)
      :classmethod:


      Parse a ``translation_layer`` config block from ``world.json``.

      Missing optional fields fall back to safe defaults so that a minimal
      ``{"enabled": true}`` block is sufficient for basic operation.

      :param data: The ``translation_layer`` dict from ``world.json``.
      :param world_root: Passed for future use (e.g. resolving relative paths
                         at parse time).  Currently unused at construction but
                         kept in the signature to avoid a breaking change later.

      :returns: A fully-populated, frozen ``TranslationLayerConfig``.



   .. py:method:: disabled()
      :classmethod:


      Return a config object that represents a disabled translation layer.

      Used as the default when a world has no ``translation_layer`` block,
      or when the server master switch is off.