############################################################################
#   This file is part of the aGrUM/pyAgrum library.                        #
#                                                                          #
#   Copyright (c) 2005-2026 by                                             #
#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
#       - Christophe GONZALES(_at_AMU)                                     #
#                                                                          #
#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
#   and/or modify it under the terms of either :                           #
#                                                                          #
#    - the GNU Lesser General Public License as published by               #
#      the Free Software Foundation, either version 3 of the License,      #
#      or (at your option) any later version,                              #
#    - the MIT license (MIT),                                              #
#    - or both in dual license, as here.                                   #
#                                                                          #
#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
#                                                                          #
#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS #
#   FOR A PARTICULAR PURPOSE  AND NONINFRINGEMENT. IN NO EVENT SHALL THE   #
#   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER #
#   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,        #
#   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR  #
#   OTHER DEALINGS IN THE SOFTWARE.                                        #
#                                                                          #
#   See LICENCES for more details.                                         #
#                                                                          #
#   SPDX-FileCopyrightText: Copyright 2005-2026                            #
#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
#       - Christophe GONZALES(_at_AMU)                                     #
#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
#                                                                          #
#   Contact  : info_at_agrum_dot_org                                       #
#   homepage : http://agrum.gitlab.io                                      #
#   gitlab   : https://gitlab.com/agrumery/agrum                           #
#                                                                          #
############################################################################

from collections.abc import MutableMapping


class Explanation(MutableMapping):
  """Structured container for the result of a Shap/Shall explanation.

  Acts as a mapping from feature names to their attribution values, and also
  carries the auxiliary data produced during the computation.
  """

  def __init__(self, values, importances, feature_names, data, baseline, func, values_type) -> None:
    """
    Parameters
    ----------
    values : dict
        Mapping from feature names to attribution values.
    importances : dict
        Global feature importances (aggregated across all instances).
    feature_names : list[str]
        Ordered list of feature names corresponding to the attribution values.
    data : object
        The input data used to compute the explanation.
    baseline : float or array-like
        The baseline (reference) prediction used as the starting point for
        attribution computation.
    func : callable
        The prediction function that was explained.
    values_type : str
        Type of attribution values (e.g. ``"shap"`` or ``"shall"``).
    """
    self._values = values
    self.importances = importances
    self.feature_names = feature_names
    self.data = data
    self.baseline = baseline
    self.func = func
    self.values_type = values_type

  def __getitem__(self, key):
    return self._values[key]

  def __setitem__(self, key, value):
    self._values[key] = value

  def __delitem__(self, key):
    del self._values[key]

  def __iter__(self):
    return iter(self._values)

  def __len__(self):
    return len(self._values)

  def __repr__(self):
    return f"Explanation(values={self._values})"
