/**
 * @license
 * Copyright 2018 Google LLC. All Rights Reserved.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * =============================================================================
 */

/* Type definitions for exporting and importing of models. */

/**
 * A map from Tensor dtype to number of bytes per element of the Tensor.
 */
export const DTYPE_VALUE_SIZE_MAP: {[dtype: string]: number} = {
  'float32': 4,
  'int32': 4,
  'uint16': 2,
  'uint8': 1,
  'bool': 1,
};

/**
 * A weight manifest.
 *
 * The weight manifest consists of an ordered list of weight-manifest groups.
 * Each weight-manifest group ("group" for short hereafter) consists of a
 * number of weight values stored in a number of paths.
 * See the documentation of `WeightManifestGroupConfig` below for more details.
 */
export declare type WeightsManifestConfig = WeightsManifestGroupConfig[];

/**
 * A weight-manifest group.
 *
 * Consists of an ordered list of weight values encoded in binary format,
 * stored in an ordered list of paths.
 */
export declare interface WeightsManifestGroupConfig {
  /**
   * An ordered list of paths.
   *
   * Paths are intentionally abstract in order to be general. For example, they
   * can be relative URL paths or relative paths on the file system.
   */
  paths: string[];

  /**
   * Specifications of the weights stored in the paths.
   */
  weights: WeightsManifestEntry[];
}

/**
 * Group to which the weight belongs.
 *
 * - 'optimizer': Weight from a stateful optimizer.
 */
export type WeightGroup = 'model'|'optimizer';

/**
 * An entry in the weight manifest.
 *
 * The entry contains specification of a weight.
 */
export declare interface WeightsManifestEntry {
  /**
   * Name of the weight, e.g., 'Dense_1/bias'
   */
  name: string;

  /**
   * Shape of the weight.
   */
  shape: number[];

  /**
   * Data type of the weight.
   */
  dtype: 'float32'|'int32'|'bool'|'string';

  /**
   * Type of the weight.
   *
   * Optional.
   *
   * The value 'optimizer' indicates the weight belongs to an optimizer
   * (i.e., used only during model training and not during inference).
   */
  group?: WeightGroup;

  /**
   * Information for dequantization of the weight.
   */
  quantization?: {
    scale: number,           // The scaling constant to multiply by.
    min: number,             // The (possibly nudged) minimum weight to add.
    dtype: 'uint16'|'uint8'  // The dtype of the quantized weights.
  };
}

/**
 * Options for saving a model.
 * @innamespace io
 */
export interface SaveConfig {
  /**
   * Whether to save only the trainable weights of the model, ignoring the
   * non-trainable ones.
   */
  trainableOnly?: boolean;

  /**
   * Whether the optimizer will be saved (if exists).
   *
   * Default: `false`.
   */
  includeOptimizer?: boolean;
}

/**
 * Result of a saving operation.
 */
export interface SaveResult {
  /**
   * Information about the model artifacts saved.
   */
  modelArtifactsInfo: ModelArtifactsInfo;

  /**
   * HTTP responses from the server that handled the model-saving request (if
   * any). This is applicable only to server-based saving routes.
   */
  responses?: Response[];

  /**
   * Error messages and related data (if any).
   */
  errors?: Array<{}|string>;
}

export declare interface ModelArtifactsInfo {
  /**
   * Timestamp for when the model is saved.
   */
  dateSaved: Date;

  /**
   * TODO (cais,yassogba) consider removing GraphDef as GraphDefs now
   * come in a JSON format and none of our IOHandlers support a non json
   * format. We could conder replacing this with 'Binary' if we want to
   * allow future handlers to save to non json formats (though they will
   * probably want more information than 'Binary').
   * Type of the model topology
   *
   * Type of the model topology
   *
   * Possible values:
   *   - JSON: JSON config (human-readable, e.g., Keras JSON).
   *   - GraphDef: TensorFlow
   *     [GraphDef](https://www.tensorflow.org/extend/tool_developers/#graphdef)
   *     protocol buffer (binary).
   */
  modelTopologyType: 'JSON'|'GraphDef';

  /**
   * Size of model topology (Keras JSON or GraphDef), in bytes.
   */
  modelTopologyBytes?: number;

  /**
   * Size of weight specification or manifest, in bytes.
   */
  weightSpecsBytes?: number;

  /**
   * Size of weight value data, in bytes.
   */
  weightDataBytes?: number;
}

/** Model training configuration. */
export declare interface TrainingConfig {
  // TODO(cais): Tighten the typing once keras spec is available to tfjs-core.
  // See
  // tslint:disable-next-line:max-line-length
  // https://github.com/tensorflow/tfjs-layers/blob/master/src/keras_format/training_config.ts
  /** Optimizer used for the model training. */
  optimizer_config: {};

  // TODO(cais): Tighten the typing once keras spec is available to tfjs-core.
  /** Loss function(s) for the model's output(s). */
  loss: string|string[]|{[key: string]: string};

  // TODO(cais): Tighten the typing once keras spec is available to tfjs-core.
  /** Metric function(s) for the model's output(s). */
  metrics?: string[]|{[key: string]: string};

  // TODO(cais): Tighten the typing once keras spec is available to tfjs-core.
  weighted_metrics?: string[];

  // TODO(cais): Tighten the typing once keras spec is available to tfjs-core.
  sample_weight_mode?: string;

  loss_weights?: number[]|{[key: string]: number};
}

/**
 * The serialized artifacts of a model, including topology and weights.
 *
 * The `modelTopology`, `trainingConfig`, `weightSpecs` and `weightData` fields
 * of this interface are optional, in order to support topology- or weights-only
 * saving and loading.
 *
 * Note this interface is used internally in IOHandlers.  For the file format
 * written to disk as `model.json`, see `ModelJSON`.
 */
export declare interface ModelArtifacts {
  /**
   * Model topology.
   *
   * For Keras-style `tf.Model`s, this is a JSON object.
   * For TensorFlow-style models (e.g., `SavedModel`), this is the JSON
   * encoding of the `GraphDef` protocol buffer.
   */
  modelTopology?: {}|ArrayBuffer;

  /**
   * Serialized configuration for the model's training.
   */
  trainingConfig?: TrainingConfig;

  /**
   * Weight specifications.
   *
   * This corresponds to the weightsData below.
   */
  weightSpecs?: WeightsManifestEntry[];

  /**
   * Binary buffer for all weight values concatenated in the order specified
   * by `weightSpecs`.
   */
  weightData?: ArrayBuffer;

  /**
   * Hard-coded format name for models saved from TensorFlow.js or converted
   * by TensorFlow.js Converter.
   */
  format?: string;

  /**
   * What library is responsible for originally generating this artifact.
   *
   * Used for debugging purposes. E.g., 'TensorFlow.js v1.0.0'.
   */
  generatedBy?: string;

  /**
   * What library or tool is responsible for converting the original model
   * to this format, applicable only if the model is output by a converter.
   *
   * Used for debugging purposes.  E.g., 'TensorFlow.js Converter v1.0.0'.
   *
   * A value of `null` means the model artifacts are generated without any
   * conversion process (e.g., saved directly from a TensorFlow.js
   * `tf.LayersModel` instance.)
   */
  convertedBy?: string|null;

  /**
   * User-defined metadata about the model.
   */
  userDefinedMetadata?: {};
}

/**
 * The on-disk format of the `model.json` file.
 *
 * TF.js 1.0 always populates the optional fields when writing model.json.
 * Prior versions did not provide those fields.
 */
export declare interface ModelJSON {
  /**
   * Model topology.
   *
   * For Keras-style `tf.Model`s, this is a JSON object.
   * For TensorFlow-style models (e.g., `SavedModel`), this is the JSON
   * encoding of the `GraphDef` protocol buffer.
   */
  modelTopology: {};

  /** Model training configuration. */
  trainingConfig?: TrainingConfig;

  /**
   * Weights manifest.
   *
   * The weights manifest consists of an ordered list of weight-manifest
   * groups. Each weight-manifest group consists of a number of weight values
   * stored in a number of paths. See the documentation of
   * `WeightsManifestConfig` for more details.
   */
  weightsManifest: WeightsManifestConfig;

  /**
   * Hard-coded format name for models saved from TensorFlow.js or converted
   * by TensorFlow.js Converter.
   */
  format?: string;

  /**
   * What library is responsible for originally generating this artifact.
   *
   * Used for debugging purposes. E.g., 'TensorFlow.js v1.0.0'.
   */
  generatedBy?: string;

  /**
   * What library or tool is responsible for converting the original model
   * to this format, applicable only if the model is output by a converter.
   *
   * Used for debugging purposes.  E.g., 'TensorFlow.js Converter v1.0.0'.
   *
   * A value of `null` means the model artifacts are generated without any
   * conversion process (e.g., saved directly from a TensorFlow.js
   * `tf.LayersModel` instance.)
   */
  convertedBy?: string|null;

  /**
   * User-defined metadata about the model.
   */
  userDefinedMetadata?: {};
}

/**
 * Type definition for handlers of loading operations.
 */
export type LoadHandler = () => Promise<ModelArtifacts>;

/**
 * Type definition for handlers of saving operations.
 */
export type SaveHandler = (modelArtifact: ModelArtifacts) =>
    Promise<SaveResult>;

/**
 * Interface for a model import/export handler.
 *
 * The `save` and `load` handlers are both optional, in order to allow handlers
 * that support only saving or loading.
 */
// tslint:disable-next-line:interface-name
export interface IOHandler {
  save?: SaveHandler;
  load?: LoadHandler;
}

/**
 * An interface for the manager of a model store.
 *
 * A model store is defined as a storage medium on which multiple models can
 * be stored. Each stored model has a unique `path` as its identifier.
 * A `ModelStoreManager` for the store allows actions including
 *
 * - Listing the models stored in the store.
 * - Deleting a model from the store.
 */
export interface ModelStoreManager {
  /**
   * List all models in the model store.
   *
   * @returns A dictionary mapping paths of existing models to their
   *   model artifacts info. Model artifacts info include type of the model's
   *   topology, byte sizes of the topology, weights, etc.
   */
  listModels(): Promise<{[path: string]: ModelArtifactsInfo}>;

  /**
   * Remove a model specified by `path`.
   *
   * @param path
   * @returns ModelArtifactsInfo of the deleted model (if and only if deletion
   *   is successful).
   * @throws Error if deletion fails, e.g., if no model exists at `path`.
   */
  removeModel(path: string): Promise<ModelArtifactsInfo>;
}

/**
 * Callback for the progress of a long-running action such as an HTTP
 * request for a large binary object.
 *
 * `fraction` should be a number in the [0, 1] interval, indicating how
 * much of the action has completed.
 */
export type OnProgressCallback = (fraction: number) => void;

/** @innamespace io */
export interface LoadOptions {
  /**
   * RequestInit (options) for HTTP requests.
   *
   * For detailed information on the supported fields, see
   * [https://developer.mozilla.org/en-US/docs/Web/API/Request/Request](
   *     https://developer.mozilla.org/en-US/docs/Web/API/Request/Request)
   */
  requestInit?: RequestInit;

  /**
   * Progress callback.
   */
  onProgress?: OnProgressCallback;

  /**
   * A function used to override the `window.fetch` function.
   */
  fetchFunc?: Function;

  /**
   * Strict loading model: whether extraneous weights or missing
   * weights should trigger an `Error`.
   *
   * If `true`, require that the provided weights exactly match those
   * required by the layers. `false` means that both extra weights
   * and missing weights will be silently ignored.
   *
   * Default: `true`.
   */
  strict?: boolean;

  /**
   * Path prefix for weight files, by default this is calculated from the
   * path of the model JSON file.
   *
   * For instance, if the path to the model JSON file is
   * `http://localhost/foo/model.json`, then the default path prefix will be
   * `http://localhost/foo/`. If a weight file has the path value
   * `group1-shard1of2` in the weight manifest, then the weight file will be
   * loaded from `http://localhost/foo/group1-shard1of2` by default. However,
   * if you provide a `weightPathPrefix` value of
   * `http://localhost/foo/alt-weights`, then the weight file will be loaded
   * from the path `http://localhost/foo/alt-weights/group1-shard1of2` instead.
   */
  weightPathPrefix?: string;

  /**
   * Whether the module or model is to be loaded from TF Hub.
   *
   * Setting this to `true` allows passing a TF-Hub module URL, omitting the
   * standard model file name and the query parameters.
   *
   * Default: `false`.
   */
  fromTFHub?: boolean;
}

/**
 * Additional options for Platform.fetch
 */
export interface RequestDetails {
  /**
   * Is this request for a binary file (as opposed to a json file)
   */
  isBinary?: boolean;
}
