humainflow-web/src/app/services/task-executions/task-executions-call.base.ts

// SPDX-FileCopyrightText: 2025-2026 Lucio Lelii <lucio.lelii@isti.cnr.it> - ISTI-CNR
// SPDX-License-Identifier: AGPL-3.0-or-later
// Attribution term under AGPL-3.0 section 7(b): see LICENSE-ADDENDUM.

import { LLMDescriptor } from '@models/flow';
import {
  BiasImpactExperimentRequest,
  BiasImpactJob,
  BiasImpactReport,
  BiasRerunRequest
} from '@models/bias-impact';
import { ExecutionEventLogEntry, TaskExecution, TaskExecutionGroup } from '@models/task-execution';
import { Observable } from 'rxjs';

export abstract class TaskExecutionsCallServiceBase {
  abstract retrieveAllTaskExecutions(): Observable<TaskExecution[]>;
  abstract retrieveTaskExecutionGroups(): Observable<TaskExecutionGroup[]>;
  abstract retrieveTaskExecution(executionId: string): Observable<TaskExecution>;
  abstract retrieveStepIterations(executionId: string, stepId: string): Observable<TaskExecution[]>;
  abstract retrieveExecutionEvents(executionId: string): Observable<ExecutionEventLogEntry[]>;
  abstract createTaskExecution(flowId: string): Observable<TaskExecution>;
  abstract rerunTaskExecution(executionId: string): Observable<TaskExecution>;
  abstract runBiasImpactExperiment(
    executionId: string,
    stepId: string,
    request: BiasImpactExperimentRequest
  ): Observable<BiasImpactJob>;
  /**
   * Asks a model to assess a comparison that has already been computed. Asynchronous like the
   * isolated experiment - one model call per compared pair - so it answers with a job to poll.
   */
  abstract judgeBiasImpactReport(reportId: string, judge: LLMDescriptor, credentialId?: string): Observable<BiasImpactJob>;
  abstract getBiasImpactJob(jobId: string): Observable<BiasImpactJob>;
  abstract createBiasedRerun(executionId: string, request: BiasRerunRequest): Observable<TaskExecution>;
  abstract compareBiasExecutions(
    baselineExecutionId: string,
    biasedExecutionId: string,
    includeRawOutputs: boolean
  ): Observable<BiasImpactReport>;
  abstract listBiasImpactReports(executionId: string): Observable<BiasImpactReport[]>;
  abstract getBiasImpactReport(reportId: string): Observable<BiasImpactReport>;
  abstract deleteTaskExecution(executionId: string): Observable<void>;
  abstract deleteTaskExecutionGroup(groupId: string): Observable<void>;
  abstract startTaskExecution(executionId: string): Observable<TaskExecution>;
  abstract simulateTaskExecution(executionId: string, simulator: LLMDescriptor, credentialId?: string): Observable<TaskExecution>;
  abstract cancelTaskExecution(executionId: string): Observable<TaskExecution>;
  abstract resumeTaskExecution(executionId: string): Observable<TaskExecution>;
  abstract prepareStringInput(
    executionId: string,
    nodeId: string,
    inputName: string,
    value: string
  ): Observable<TaskExecution>;
  abstract prepareStringArrayInput(
    executionId: string,
    nodeId: string,
    inputName: string,
    values: string[]
  ): Observable<TaskExecution>;
  abstract prepareFileInput(
    executionId: string,
    nodeId: string,
    inputName: string,
    file: File
  ): Observable<TaskExecution>;
  abstract prepareFileArrayInput(
    executionId: string,
    nodeId: string,
    inputName: string,
    files: File[]
  ): Observable<TaskExecution>;
  abstract prepareGlobalStringInput(
    executionId: string,
    inputName: string,
    value: string
  ): Observable<TaskExecution>;
  abstract prepareGlobalStringArrayInput(
    executionId: string,
    inputName: string,
    values: string[]
  ): Observable<TaskExecution>;
  /**
   * Sets several global inputs in one request. The single-key endpoint had to be called once per
   * input, and those calls raced each other on the same execution.
   */
  abstract prepareGlobalInputs(
    executionId: string,
    values: Record<string, string | string[]>
  ): Observable<TaskExecution>;
  abstract prepareGlobalFileInput(
    executionId: string,
    inputName: string,
    file: File
  ): Observable<TaskExecution>;
  abstract prepareGlobalFileArrayInput(
    executionId: string,
    inputName: string,
    files: File[]
  ): Observable<TaskExecution>;
  /**
   * `iteration`, when given, is the round of its loop the answer is for: the server refuses it if
   * the node has moved on to another, rather than taking it as the answer to a question not seen.
   */
  abstract submitInteractionText(
    executionId: string,
    nodeId: string,
    fieldName: string,
    value: string,
    iteration?: number
  ): Observable<TaskExecution>;
  /**
   * Submits a human evaluation whole - every criterion and the notes in one call - because the
   * fields are one judgement, and half of one recorded on the step is worse than none.
   */
  abstract submitEvaluation(
    executionId: string,
    nodeId: string,
    verdict: Record<string, string>,
    notes: string,
    iteration?: number
  ): Observable<TaskExecution>;
  abstract attachEvaluationEvidence(
    executionId: string,
    nodeId: string,
    files: File[],
    iteration?: number
  ): Observable<TaskExecution>;
  /** Asks to see the reference verdict; the execution records that it was seen before judging. */
  abstract revealEvaluationReference(
    executionId: string,
    nodeId: string,
    iteration?: number
  ): Observable<TaskExecution>;
  abstract provideAuthorization(
    executionId: string,
    key: string,
    value: string
  ): Observable<TaskExecution>;
}