# Jubatus: Online machine learning framework for distributed environment
# Copyright (C) 2011,2012 Preferred Networks and Nippon Telegraph and Telephone Corporation.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License version 2.1 as published by the Free Software Foundation.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

message estimate_result {
  0: string label
  1: double score
}

message labeled_datum {
  0: string label
  1: datum data
}

service classifier {

  #- - Parameters:
  #-
  #-  - ``name`` : a string value to uniquely identifies a task in zookeeper quorum
  #-  - ``data`` : list of tuple of label and datum
  #-
  #- - Returns:
  #-
  #-  - Number of trained datum if this function updates models successfully.
  #-
  #- Training model at a server chosen randomly. ``tuple<string, datum>`` is a tuple of datum and it's label.
  #- This function is designed to allow bulk update with list of tuple of label and datum.
  #@random #@nolock #@pass
  int train(0: list<labeled_datum> data)

  #- - Parameters:
  #-
  #-  - ``name`` : a string value to uniquely identifies a task in zookeeper quorum
  #-  - ``data`` : list of datum for classify
  #-
  #- - Returns:
  #-
  #-  - List of estimate_results
  #-
  #- Estimating a result at a server choosen randomly. ``estimate_results`` is a list of tuple of label and it's reliablity value.
  #@random #@nolock #@pass
  list<list<estimate_result> > classify(0: list<datum> data)

  #- - Returns:
  #-
  #-  - List of Label
  #-
  #-  Get all labels in the model
  #@random #@nolock #@pass
  map<string, ulong> get_labels()

  #- - Parameters:
  #-
  #-  - ``new_label`` : name of the new label
  #-
  #- - Returns:
  #-
  #-  - True if this function appends label successfully.
  #-
  #-  Append new label with no datum
  #@broadcast #@nolock #@all_and
  bool set_label(0: string new_label)

  #@broadcast #@nolock #@all_and
  bool clear()

  #@broadcast #@nolock #@all_or
  bool delete_label(0: string target_label)
}
