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

.. py:module:: pipeworks_mud_mapper.services

.. autoapi-nested-parse::

   Service layer for PipeWorks MUD Mapper.

   This module provides the business logic layer that sits between the UI
   (Dash callbacks) and the data models. Services are designed to be:

   1. **Framework-agnostic**: No Dash imports - can be tested independently
   2. **Stateless**: Operate on models passed as arguments
   3. **Focused**: Each service has a single responsibility

   Architecture
   ------------
   The service layer implements the "thin callback" pattern where Dash callbacks
   become simple orchestrators that:

   1. Extract data from component state
   2. Call service functions
   3. Return updated state to components

   This separation enables:

   - Unit testing without Dash test harnesses
   - Reuse in CLI tools or other interfaces
   - Clear boundaries between UI and business logic

   Service Modules
   ---------------
   **zone_service**
       File I/O operations: load, save, export, create new zones.
       Handles the two-file workflow (map files vs zone files).

   **validation_service**
       Map validation: connectivity, exit consistency, language-direction
       conflicts. Returns structured warnings for UI display.

   Usage
   -----
   In a Dash callback::

       from pipeworks_mud_mapper.services import zone_service

       @app.callback(...)
       def handle_save(map_data, filename):
           map_file = MapFile.from_dict(map_data)
           zone_service.save_map_file(map_file, Path(filename))
           return "Saved successfully"

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



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/pipeworks_mud_mapper/services/api_client/index
   /autoapi/pipeworks_mud_mapper/services/api_db_service/index
   /autoapi/pipeworks_mud_mapper/services/app_config/index
   /autoapi/pipeworks_mud_mapper/services/db_tools/index
   /autoapi/pipeworks_mud_mapper/services/description_validator/index
   /autoapi/pipeworks_mud_mapper/services/exit_utils/index
   /autoapi/pipeworks_mud_mapper/services/io_queue/index
   /autoapi/pipeworks_mud_mapper/services/map_db_service/index
   /autoapi/pipeworks_mud_mapper/services/ollama_assets/index
   /autoapi/pipeworks_mud_mapper/services/ollama_client/index
   /autoapi/pipeworks_mud_mapper/services/ollama_config/index
   /autoapi/pipeworks_mud_mapper/services/ollama_state/index
   /autoapi/pipeworks_mud_mapper/services/ollama_ui/index
   /autoapi/pipeworks_mud_mapper/services/state/index
   /autoapi/pipeworks_mud_mapper/services/template_service/index
   /autoapi/pipeworks_mud_mapper/services/validation_service/index
   /autoapi/pipeworks_mud_mapper/services/world_service/index
   /autoapi/pipeworks_mud_mapper/services/zone_service/index