How would you model reliability in an async analysis report API?

general
1

I have a programming question about modeling state and response shape for a long-running text analysis endpoint.

The flow is:

  1. User submits pasted text or a supported document.
  2. Client normalizes the input and sends it to an API route.
  3. The API validates length, file size, and rate limits.
  4. The server calls a provider through an adapter.
  5. The response is converted into a report with scores, sentence highlights, reliability notes, and limitations.
  6. The user can copy or export the report.

The part I am trying to model cleanly is the report contract. I do not want the UI to treat a provider score as a definitive answer, and I do not want a fallback result to look the same as a normal provider result.

One shape I am considering is:

type ReportReliability = "low" | "medium" | "high";
type ProviderState = "provider_result" | "fallback_result" | "failed";

type AnalysisReport = {
  id: string;
  providerState: ProviderState;
  reliability: ReportReliability;
  scores: {
    aiLikelihood: number;
    likelyHuman: number;
  };
  sentenceHighlights: Array<{
    text: string;
    score?: number;
    reason?: string;
  }>;
  limitations: string[];
};

Would you keep provider state, reliability, and limitations in one report object, or split them into separate metadata and content objects so the UI has to render caveats explicitly?

The main bug I want to avoid is a future UI change that displays only the numeric score and accidentally drops the reliability and limitation fields. No link or product review is needed; this is a TypeScript/API modeling question.