iios/packages/iios-contracts/src/inference.ts

/**
 * The AI inference port (P7). A standalone contract — deliberately NOT part of the
 * sealed `IiosPlatformPorts`: AI is an internal "AI Factory" whose model execution
 * routes through the Capability Broker in P9. In P7 it is a faked, deterministic,
 * golden provider (no network). Every result carries the provenance the critics
 * mandate (model/prompt version, tokens, cost, confidence, abstention, evidence).
 */

export type AiJobType = 'CLASSIFY' | 'SUMMARIZE' | 'EXTRACT';

export type AiArtifactType = 'CLASSIFICATION' | 'SUMMARY' | 'TRANSCRIPT' | 'DIGEST' | 'EXTRACTION';

export type AiClaimType = 'MODERATION_FLAG' | 'EVENT' | 'FAQ' | 'INTENT' | 'PRIORITY';

export interface InferenceRequest {
  jobType: AiJobType;
  text: string;
  purpose: string;
  scopeId: string;
  /** The kernel interaction this inference is about — used as the default evidence source. */
  interactionId?: string;
}

export interface InferenceClaim {
  claimType: AiClaimType;
  claimJson: Record<string, unknown>;
  confidence: number;
}

export interface InferenceEvidence {
  sourceType: string;
  sourceId: string;
  spanRef?: string;
  relevanceScore?: number;
}

export interface InferenceModelRun {
  model: string;
  modelVersion: string;
  promptVersion: string;
  tokensIn: number;
  tokensOut: number;
  costUnits: number;
  latencyMs: number;
}

export interface InferenceResult {
  artifactType: AiArtifactType;
  content: unknown;
  confidence: number;
  explanation?: string;
  /** Set when the model declines to assert a claim (Scenario 7 abstention). */
  abstentionReason?: string;
  claims: InferenceClaim[];
  evidence: InferenceEvidence[];
  modelRun: InferenceModelRun;
}

export interface InferencePort {
  infer(req: InferenceRequest): Promise<InferenceResult>;
}