Models Proto Definition

syntax = "proto3";

package athena;

option csharp_namespace = "Resolver.Athena.Grpc";
option java_outer_classname = "AthenaModelsProto";
option java_package = "com.resolver.athena.grpc";
option objc_class_prefix = "RAT";
option php_namespace = "Resolver\\Athena\\Grpc";
option ruby_package = "Resolver::Athena::Grpc";
option swift_prefix = "RAT";

// Response message for ListDeployments RPC
// Contains the list of active deployments and their details.
message ListDeploymentsResponse {
  // List of active deployments with their backlog information.
  repeated Deployment deployments = 1;
}

// A single active deployment part of a `ListDeployments` response
message Deployment {
  // active deployment identifier
  string deployment_id = 1;

  // Backlog of classification responses in this deployment
  int32 backlog = 2;
}

// The request message containing the image data to classify.
// Each request represents a batch of images that should be processed within
// the same deployment context.
message ClassifyRequest {
  // Client's unique identifier for this deployment. Responses returned will be
  // sent to a client with a matching deployment_id.
  string deployment_id = 1;

  // Array of images to be classified in this request batch
  // Allows sending multiple images in a single request for efficiency.
  repeated ClassificationInput inputs = 2;
}

// A single image within a classification request batch.
// Contains all necessary metadata and data for classifying one image.
message ClassificationInput {
  // The affiliate or source system that provided this image
  // Used for tracking, analytics, and routing purposes.
  string affiliate = 1;

  // Unique identifier for correlating this input with its response
  // Must be unique within the deployment to properly match responses
  string correlation_id = 2;

  // Specifies the encoding/compression format of the image data
  // Allows the server to properly decode the image before classification
  RequestEncoding encoding = 3;

  // The raw image data bytes in the format specified by encoding
  // Can be compressed or uncompressed based on the encoding field
  bytes data = 4;

  // The image file format of the data bytes
  ImageFormat format = 5;

  // Hashes of the image data, can be multiple depending on image processing
  // (e.g. of raw bytes, jpeg image, etc.) but must be for a single image.
  repeated ImageHash hashes = 6;
}

// The response message containing the classification results.
// Sent back to clients for each processed batch, containing either
// a global error or individual results for each image in the batch.
message ClassifyResponse {
  // Global error affecting the entire batch/request
  // If present, indicates that the entire request failed and no individual
  // image results will be provided
  ClassificationError global_error = 1;

  // Array of classification results, one for each input image
  // Will be empty if global_error is present
  repeated ClassificationOutput outputs = 2;
}

// Individual classification result for a single image.
// Contains the correlation ID and classification results for one image.
message ClassificationOutput {
  // Matches the correlationId from the corresponding ClassificationInput
  // Allows clients to match responses with their original requests
  string correlation_id = 1;

  // Array of all classifications detected for this image
  // Multiple classifications may be returned with different confidence levels
  repeated Classification classifications = 2;

  // Error information if this specific image classification failed
  // If present, indicates that this particular image could not be processed
  ClassificationError error = 3;
}

// A single classification result for an image.
// Represents one detected category with its confidence score.
message Classification {
  // Human-readable label describing what was classified
  // Examples: "CatA", "CatB", "Indicative", "Distraction", etc.
  string label = 1;

  // Confidence score between 0.0 and 1.0 indicating certainty
  // Higher values indicate greater confidence in the classification
  float weight = 2;
}

// Error information for failed classification attempts.
// Provides details about why a classification could not be completed.
message ClassificationError {
  // Error code indicating the type of failure
  ErrorCode code = 1;

  // Human-readable error message providing details about the failure
  string message = 2;

  // Additional context or details about the error (optional)
  string details = 3;
}

// Hash information for an image.
message ImageHash {
    // The hash value of the image data
    string value = 1;

    // The type of hash algorithm used to generate the hash value
    HashType type = 2;
}

// Enumeration of possible classification error codes.
enum ErrorCode {
  // Unknown or unspecified error
  ERROR_CODE_UNSPECIFIED = 0;

  // Image is too large to process
  ERROR_CODE_IMAGE_TOO_LARGE = 2;

  // Opaque error from the classifier
  ERROR_CODE_MODEL_ERROR = 3;

  // Attempt to send data for an affiliate which is not granted to the current
  // client.
  ERROR_CODE_AFFILIATE_NOT_PERMITTED = 4;

  // The format of the deployment ID is not valid. Deployment IDs must be
  // non-empty strings of up to 64 characters.
  ERROR_CODE_DEPLOYMENT_ID_INVALID = 5;

  // The format of the correlation ID is not valid. Correlation IDs must be
  // non-empty strings of up to 64 characters.
  ERROR_CODE_CORRELATION_ID_INVALID = 6;
}

// Enumeration of supported image data encoding formats.
// Determines how the server should interpret the image data bytes.
enum RequestEncoding {
  // Unspecified encoding. Assumed to be uncompressed.
  REQUEST_ENCODING_UNSPECIFIED = 0;

  // Uncompressed raw image data (e.g., raw RGB pixels, BMP, etc.)
  REQUEST_ENCODING_UNCOMPRESSED = 1;

  // Brotli-compressed image data for reduced bandwidth usage
  // Server will decompress using Brotli algorithm before processing
  REQUEST_ENCODING_BROTLI = 2;
}

// Enumeration of supported image file formats.
// Specifies the image file format structure for proper parsing.
enum ImageFormat {
  IMAGE_FORMAT_UNSPECIFIED = 0;
  IMAGE_FORMAT_GIF = 1;
  IMAGE_FORMAT_JPEG = 2; // Covers .jpeg, .jpg, .jpe extensions
  IMAGE_FORMAT_BMP = 3;
  IMAGE_FORMAT_DIB = 4;
  IMAGE_FORMAT_PNG = 5;
  IMAGE_FORMAT_WEBP = 6;
  IMAGE_FORMAT_PBM = 7;
  IMAGE_FORMAT_PGM = 8;
  IMAGE_FORMAT_PPM = 9;
  IMAGE_FORMAT_PXM = 10;
  IMAGE_FORMAT_PNM = 11;
  IMAGE_FORMAT_PFM = 12;
  IMAGE_FORMAT_SR = 13;
  IMAGE_FORMAT_RAS = 14;
  IMAGE_FORMAT_TIFF = 15; // Covers .tiff, .tif extensions
  IMAGE_FORMAT_HDR = 16;
  IMAGE_FORMAT_PIC = 17;
  IMAGE_FORMAT_RAW_UINT8 = 18; // Raw unsigned 8-bit image data (RGB, C order array)
}

// Enumeration of hash types supported for image hashing.
enum HashType {
    HASH_TYPE_UNKNOWN = 0;
    HASH_TYPE_MD5 = 1;
    HASH_TYPE_SHA1 = 2;
}