syntax = "proto3";

package worldmonitor.news.v1;

import "buf/validate/validate.proto";

// SummarizeArticleRequest specifies parameters for LLM article summarization.
message SummarizeArticleRequest {
  // LLM provider: "ollama", "groq", "openrouter"
  string provider = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1
  ];
  // Headlines to summarize. Up to 10 raw headlines are used for request
  // identity/cache matching; the LLM prompt uses up to 5 unique, non-empty
  // sanitized headline/body pairs.
  repeated string headlines = 2 [(buf.validate.field).repeated.min_items = 1];
  // Summarization mode: "brief", "analysis", "translate", "" (default).
  string mode = 3;
  // Geographic signal context to include in the prompt.
  string geo_context = 4;
  // Variant: "full", "tech", or target language for translate mode.
  string variant = 5;
  // Output language code, default "en".
  string lang = 6;
  // Optional system prompt append for analytical framework instructions.
  string system_append = 7;
  // Optional article bodies paired 1:1 with `headlines`. When bodies[i] is
  // non-empty, the prompt interleaves it as grounding context under
  // headlines[i]; when empty, behavior is identical to headline-only today.
  // Callers may supply a shorter array; missing entries are treated as empty.
  // Each body is subject to the same sanitisation as headlines before reaching
  // the LLM prompt.
  repeated string bodies = 8;
}

// SummarizeStatus indicates the outcome of a summarization request.
enum SummarizeStatus {
  SUMMARIZE_STATUS_UNSPECIFIED = 0;
  SUMMARIZE_STATUS_SUCCESS = 1;
  SUMMARIZE_STATUS_CACHED = 2;
  SUMMARIZE_STATUS_SKIPPED = 3;
  SUMMARIZE_STATUS_ERROR = 4;
}

// SummarizeArticleResponse contains the LLM summarization result.
message SummarizeArticleResponse {
  // The generated summary text.
  string summary = 1;
  // Model identifier used for generation.
  string model = 2;
  // Provider that produced the result (or "cache").
  string provider = 3;
  // Token count from the LLM response.
  int32 tokens = 5;
  // Whether the client should try the next provider in the fallback chain.
  bool fallback = 6;
  // Error message if the request failed.
  string error = 9;
  // Error type/name (e.g. "TypeError").
  string error_type = 10;
  // Consolidated status of the summarization request.
  SummarizeStatus status = 11;
  // Human-readable detail for non-success statuses (skip reason, etc.).
  string status_detail = 12;

  // Reserved field numbers from consolidated fields:
  // 4 = cached (bool), 7 = skipped (bool), 8 = reason (string).
  reserved 4, 7, 8;
  reserved "cached", "skipped", "reason";
}
