pipeworks_mud_mapper.layout.ollama_panel
========================================

.. py:module:: pipeworks_mud_mapper.layout.ollama_panel

.. autoapi-nested-parse::

   Ollama LLM Assistant panel component.

   The Ollama panel provides an interface for generating room descriptions
   using local LLM models via Ollama. It includes template selection for
   pre-configured system prompts, model management, seed control for
   reproducible generation, and configurable model parameters.

   Component Structure
   -------------------
   ::

       ┌────────────────────────────────────────────────────────────────────┐
       │ 🤖 LLM Assistant (Ollama)                                          │
       ├────────────────────────────────────────────────────────────────────┤
       │ Server: [http://...] [↻]  Model: [dropdown]  Template: [dropdown]  │
       │ ○ Connected                                                        │
       │                                                                    │
       │ ▶ System Prompt              ▶ Parameters                          │
       │                                                                    │
       │ User Prompt: [Preset ▾]                         [Use Description]  │
       │ [________________________]                                         │
       │                                                                    │
       │ [Generate ✨]                                                       │
       │                                                                    │
       │ Response:                                                          │
       │ [________________________]                                         │
       │ [Send to Description] [Copy]                                       │
       └────────────────────────────────────────────────────────────────────┘

   Component IDs
   -------------
   **Server and Model Selection:**

   - ``ollama-server-url``: Input for Ollama server URL
   - ``ollama-model-dropdown``: Dropdown to select Ollama model
   - ``ollama-refresh-models-btn``: Button to refresh model list
   - ``ollama-refresh-icon``: Icon inside refresh button (for spinning animation)
   - ``ollama-connection-status``: Connection status indicator
   - ``ollama-template-dropdown``: Dropdown to select prompt template

   **System Prompt Section (collapsible, hidden by default):**

   - ``ollama-system-prompt-toggle``: Button to toggle system prompt visibility
   - ``ollama-system-prompt-chevron``: Chevron icon for collapse state
   - ``ollama-system-prompt-collapse``: Collapsible wrapper for system prompt
   - ``ollama-system-prompt``: Textarea for system prompt (read-only when template selected)
   - ``ollama-copy-system-prompt-btn``: Clipboard component to copy system prompt

   **Parameters Section (collapsible, hidden by default):**

   - ``ollama-params-toggle``: Button to toggle parameters visibility
   - ``ollama-params-chevron``: Chevron icon for params collapse state
   - ``ollama-params-collapse``: Collapsible wrapper for parameters

   **Seed Controls:**

   - ``ollama-seed-value``: Input for seed value (-1 for random, 0+ for fixed)
   - ``ollama-seed-decrease``: Button to decrement seed
   - ``ollama-seed-increase``: Button to increment seed
   - ``ollama-seed-random-check``: Checkbox for random mode (sets seed to -1)

   **Model Parameters:**

   - ``ollama-temperature``: Input for temperature (creativity/randomness, 0.0-2.0)
   - ``ollama-top-k``: Input for top_k (vocabulary filtering, 1-100)
   - ``ollama-top-p``: Input for top_p (nucleus sampling threshold, 0.0-1.0)
   - ``ollama-num-ctx``: Input for num_ctx (context window in tokens, 512-8192)
   - ``ollama-num-predict``: Input for num_predict (max output tokens, 30-2048)

   **User Prompt and Generation:**

   - ``ollama-user-prompt``: Textarea for user prompt
   - ``ollama-populate-prompt-btn``: Button to populate prompt from room description
   - ``ollama-generate-btn``: Button to generate description
   - ``ollama-generate-icon``: Icon inside generate button (for loading state)
   - ``ollama-generate-text``: Text inside generate button (changes during generation)

   **Response and Actions:**

   - ``ollama-response``: Textarea for LLM response
   - ``ollama-send-to-description-btn``: Button to send response to room description
   - ``ollama-clipboard``: Clipboard component for copying response
   - ``ollama-clipboard-feedback``: Clipboard copy feedback message
   - ``ollama-status``: Status message area

   Parameter Defaults
   ------------------
   The following default values are used for model parameters:

   +---------------+---------+-----------+----------------------------------------------+
   | Parameter     | Default | Range     | Purpose                                      |
   +===============+=========+===========+==============================================+
   | seed          | -1      | -1 or 0+  | -1 = random seed, 0+ = reproducible          |
   +---------------+---------+-----------+----------------------------------------------+
   | temperature   | 0.7     | 0.0-2.0   | Controls creativity/randomness of output     |
   +---------------+---------+-----------+----------------------------------------------+
   | top_k         | 40      | 1-100     | Limits vocabulary to top K probable tokens   |
   +---------------+---------+-----------+----------------------------------------------+
   | top_p         | 0.9     | 0.0-1.0   | Nucleus sampling threshold (cumulative prob) |
   +---------------+---------+-----------+----------------------------------------------+
   | num_ctx       | 4096    | 512-8192  | Context window size in tokens                |
   +---------------+---------+-----------+----------------------------------------------+
   | num_predict   | 512     | 30-2048   | Maximum number of tokens to generate         |
   +---------------+---------+-----------+----------------------------------------------+

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



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.layout.ollama_panel.create_ollama_panel


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

.. py:function:: create_ollama_panel()

   Create the Ollama LLM Assistant panel component.

   The Ollama panel provides:

   - Server connection management (URL input, refresh button, status indicator)
   - Model selection dropdown (populated from connected Ollama server)
   - Template selection for pre-configured system prompts
   - Collapsible system prompt viewer (read-only when using templates)
   - Collapsible parameters section with seed control and model parameters
   - User prompt input with "Use Description" button
   - Generate button with loading state feedback
   - Response display with copy and send-to-description actions

   :returns: Bootstrap Card containing the complete Ollama LLM interface.
   :rtype: :py:class:`dbc.Card`

   .. admonition:: Notes

      - System prompt and parameters sections are hidden by default for a cleaner UI
      - System prompt is read-only when a template is selected (enforces template integrity)
      - Templates are loaded from data/ollama/templates/ directory
      - Uses /api/chat endpoint for proper system/user message separation
      - Seed of -1 means random (uses isolated RNG to avoid poisoning global state)
      - Callback changes button state during generation for user feedback

   .. admonition:: Examples

      The Ollama panel is typically used within the main layout::
      
          >>> from pipeworks_mud_mapper.layout.ollama_panel import create_ollama_panel
          >>> panel = create_ollama_panel()
          >>> # Panel contains all ollama-* component IDs