mud_server.admin_gradio.api.ollama
==================================

.. py:module:: mud_server.admin_gradio.api.ollama

.. autoapi-nested-parse::

   Ollama API client for MUD Server.

   This module handles all Ollama LLM-related operations:
   - Executing Ollama commands on specified servers
   - Clearing conversation context

   All functions require admin or superuser role and follow a consistent pattern:
       - Validate session state and admin permissions
       - Validate input
       - Make API request using BaseAPIClient with extended timeout
       - Return standardized response dictionaries

   Response Format:
       All functions return dictionaries with:
       {
           "success": bool,         # Whether operation succeeded
           "message": str,          # Command output or status message
           "data": None,
           "error": str | None,     # Error details if failed
       }



Classes
-------

.. autoapisummary::

   mud_server.admin_gradio.api.ollama.OllamaAPIClient


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

.. py:class:: OllamaAPIClient(server_url = None)

   Bases: :py:obj:`mud_server.admin_gradio.api.base.BaseAPIClient`


   API client for Ollama LLM operations.

   This client handles Ollama command execution and context management
   for admin and superuser roles.

   .. admonition:: Example

      >>> client = OllamaAPIClient()
      >>> result = client.execute_command(
      ...     session_id="admin123",
      ...     role="admin",
      ...     server_url="http://localhost:11434",
      ...     command="list"
      ... )
      >>> if result["success"]:
      ...     print(result["message"])

   Initialize the base API client.

   :param server_url: Optional server URL override. If not provided,
                      uses MUD_SERVER_URL environment variable or defaults
                      to http://localhost:8000


   .. py:method:: execute_command(session_id, role, server_url, command)

      Execute an Ollama command on the specified server (Admin/Superuser only).

      Supported commands:
      - list: List available models
      - ps: Show running models
      - pull <model>: Download a model
      - rm <model>: Remove a model
      - And other Ollama CLI commands

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)
      :param server_url: URL of the Ollama server
      :param command: Ollama command to execute

      :returns:

                {
                    "success": bool,
                    "message": str,          # Command output
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = OllamaAPIClient()
         >>> result = client.execute_command(
         ...     session_id="admin123",
         ...     role="admin",
         ...     server_url="http://localhost:11434",
         ...     command="list"
         ... )
         >>> result["success"]
         True

      .. note::

         Long-running operations like 'pull' use a 5-minute timeout.
         If the request times out, the operation may still be running
         on the server. Use 'ps' to check status.



   .. py:method:: clear_context(session_id, role)

      Clear Ollama conversation context for the current session (Admin/Superuser only).

      This resets the conversation history, allowing you to start fresh without
      previous context affecting new queries.

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)

      :returns:

                {
                    "success": bool,
                    "message": str,
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = OllamaAPIClient()
         >>> result = client.clear_context(session_id="admin123", role="admin")
         >>> result["success"]
         True
         >>> "Context cleared" in result["message"]
         True