proto.atd

(** types for the protocol between the master and worker, and among
    workers.  There is at most one worker per host, serving on a
    pre-determined port (as a means of achieving uniqueness) *)

type worker_id = string
type task_id = string
type host = string
type feature_id = int

type id = {
  worker_id : worker_id ;
  user : string ; (* name of user owning the worker process *)
}

type known_worker = (worker_id * host list)
(* a worker peer may be accessible via multiple ip addresses (eg
   when a host has more than one network interface) *)

type known_workers = known_worker list

(* feature metadata *)
type t <ocaml_biniou module="Dog_b" ocaml_json module="Dog_j">= abstract

type loss_type = [ Logistic | Square ]

type config  = {
  task_id : task_id;
  loss_type : loss_type;
  dog_t : t;
  dog_file_size : int;
  y_feature : (feature_id * string);
  fold_feature_opt : (feature_id * string) option;
  random_seed : int list <ocaml repr="array">;
  num_folds : int;
}

(*
type ufeature <ocaml_biniou module="Dog_b" ocaml_json module="Dog_j">= abstract
type ifeature <ocaml_biniou module="Dog_b" ocaml_json module="Dog_j">= abstract
*)

type point = {
  (* what is the value of the piecewise function at the split? *)
  s_gamma : float ;

  (* how many observations does the split cover? *)
  s_n : int ;

  (* what is the loss? *)
  s_loss  : float ;
}

type ordinal_split = {
  os_feature_id : feature_id ;
  os_split : int ;
  os_left : point ;
  os_right : point ;
}

type categorical_split = (ordinal_split * int list <ocaml repr="array">)

type split = [
  | OrdinalSplit of ordinal_split
  | CategoricalSplit of categorical_split
]

type loss_split_opt = (float * split) option

type push = {
  feature_id : feature_id ;
  split : split
}

type to_worker_in_acquired = [
  | Configure of config
]

type to_worker_in_learning_or_configured = [
  | GetFeaturesFromPeers of feature_id list
  (* instruct the worker to acquire these features from any of its
     collaborating peers, if it doesn't already have them; it is not
     guaranteed that a collaborating peer has that feature. *)

  | GetFeatures of feature_id list
  (* get feature _data_ (rather than metadata), from _this_ worker
     (rather than its peers) *)

  | AddFeatures of (feature_id list * [BestAndPartition | PartitionOnly])
  (* add a feature to the set used for finding a best split, or used
     for partitioning of the observations; a feature may
     simultaneously serve as both *)
]

type learn = {
  fold : int ;
  learning_rate : float
}

type to_worker_in_configured = [
  | Learn of learn
]

type to_worker_in_learning = [
  | Sample

  | BestSplit
  (* get the best split among all the worker's active features  *)

  | Push of push

  | Ascend

  | Descend of [Left | Right]

  | CopyFeatures of (feature_id * string) list
]

type to_worker = [
  | Id
  (* what is the worker id? *)

  | InformPeerHosts of host list
  (* tell the worker of one its peers; it may or may not collaborate
     on the worker's task *)

  | Acquire of task_id
  (* client tries to assert his ownership of worker *)

  | Acquired of (task_id * to_worker_in_acquired)

  | Configured of (task_id * to_worker_in_configured)

  | Learning of (task_id * to_worker_in_learning)

]

type from_worker = [
  | Error of string
  | AckId of id
  | AckBestSplit of loss_split_opt
  | AckSample
  | AckAcquire of bool
  | AckConfigure
  | AckSetRandomSeed
  | AckAddFeatures
  | AckPush
  | AckAscend
  | AckDescend
  | AckCopyFeatures
  | AckLearn
]