Skip to main content

Events

:::info Source Sourced from services/ai-gateway-service/EVENT_SCHEMAS.md in the documentation repo. :::

1. Envelope​

Standard. retentionClass = regulated (18 months hot + 7 years cold — EU AI Act).

2. Events Published​

2.1 ai.gateway.call.completed.v1​

Canonical gateway call traceability event (US-82 / platform audit). Replaces the legacy working name ai.completion.finished.v1 used in early drafts; implementations MUST emit this type (AiGatewayEventTypes.GATEWAY_CALL_COMPLETED).

interface GatewayCallCompletedV1 {
  tenantId: TenantId;
  userId: UserId;
  completionId: CompletionId;
  promptId?: PromptId;
  promptVersion?: SemVer;
  modelId: ModelId;
  tokens: { in: number; out: number };
  costMicroUSD: number;
  cacheHit: boolean;
  safety: {
    input: { overallAction: 'allow' | 'warn' | 'block' };
    output: { overallAction: 'allow' | 'warn' | 'block' };
  };
  latencyMs: number;
  traceId: string;
  local: boolean;
  completedAt: ISODate;
}

2.2 ai.completion.refused.v1​

interface CompletionRefusedV1 {
  tenantId: TenantId;
  userId: UserId;
  promptId?: PromptId;
  reason: 'safety' | 'budget' | 'provider' | 'policy' | 'schema';
  details: string;
  refusedAt: ISODate;
}

2.3 ai.budget.exhausted.v1​

interface BudgetExhaustedV1 {
  tenantId: TenantId;
  period: 'day' | 'month';
  limitMicroUSD: number;
  usedMicroUSD: number;
  exhaustedAt: ISODate;
}

2.4 ai.safety.violation.v1​

interface SafetyViolationV1 {
  completionId?: CompletionId;
  tenantId: TenantId;
  userId: UserId;
  stage: 'input' | 'output';
  category: string;
  score: number;
  action: 'warn' | 'block';
  at: ISODate;
}

2.5 ai.prompt.version_published.v1​

interface PromptPublishedV1 {
  promptId: PromptId;
  tenantId: TenantId | null;
  version: SemVer;
  publishedBy: UserId;
  publishedAt: ISODate;
  evalScore?: number;
}

2.6 ai.embedding.created.v1​

interface EmbeddingCreatedV1 {
  embeddingId: EmbeddingId;
  tenantId: TenantId;
  modelId: ModelId;
  sourceRef: { kind: string; id: string };
  createdAt: ISODate;
}

2.7 ai.audit.entry.v1​

Audit firehose for platform-wide retention: safety/PII decisions, redaction summaries (hashes / categories — no raw PII). Consumed by the shared audit store ingestion path (e.g. analytics-service audit tier). Epic US-79 / US-80 reference this event; this file is the naming contract — user-story text in docs/07-epics-and-user-stories.md must match here.

/** No raw user content — summaries, labels, and fingerprints only. */
interface AuditEntryV1 {
  auditEntryId: ULID;
  tenantId: TenantId;
  userId: UserId;
  source: 'ai-gateway';
  kind: 'moderation' | 'safety' | 'pii_redaction' | 'refusal' | 'policy';
  correlationId: ULID;
  completionId?: CompletionId;
  stage?: 'input' | 'output' | 'pipeline';
  /** Human-readable label for operators; must not contain PII or raw prompts. */
  summary: string;
  /** e.g. moderation categories or PII class labels (no spans of original text). */
  categories?: string[];
  /** Stable hash of redacted content or request fingerprint for dedup/tuning — not reversible to PII. */
  contentFingerprint?: string;
  /** Bounded, non-PII tags (e.g. outcome=allow|block, policyVersion). */
  metadata?: Record<string, string>;
  recordedAt: ISODate;
}

2.8 ai.inference.local.completed.v1​

Emitted when a device replays offline local structured inference telemetry to POST /api/v1/ai/local-inference/telemetry (EP-19 / US-99). One outbox row per completed local completion; batch replay is idempotent using deterministic outbox row ids derived from (tenantId, Idempotency-Key, index, completionId, occurredAt).

interface LocalInferenceCompletedV1 {
  tenantId: TenantId;
  userId: UserId;
  completionId: CompletionId;
  promptId?: PromptId;
  surface: 'tutor_turn' | 'summary' | 'example' | 'practice' | 'other';
  modelId: ModelId;
  latencyMs: number;
  occurredAt: ISODate;
  deviceId?: string;
}

3. Events Consumed​

  • gdpr.subject_request.received.v1 — erase embeddings + audit entries for user.
  • tenant.plan.changed.v1 — adjust AI budgets.
  • billing.payment.succeeded.v1 — topup AI budget (if tenant bought AI credit pack).

4. Versioning​

v1 additive. New prompts / models are additive.

5. Idempotency​

  • Completion dedup on (promptHash + input fingerprint + model + tenant) when cacheable.
  • Inbox dedups on events.

6. Outbox / Inbox​

Standard. Events also firehosed to analytics + audit tier.

7. Partition Key​

  • tenantId for per-tenant ordering.
  • userId for tutor turns (consumer groups by session).

8. DLQ​

ai.dlq — alerts on non-empty.