Eve library

OSHUN V1 Metis `AvatarTeacherProfile` Contract

Spec

Revision 1

On this page

Status: Active

Date: April 10, 2026

Owners: OSHUN Metis Engineering, OSHUN Psyche, OSHUN Aja, OSHUN Safety, OSHUN Product

Related:

  • docs/releases/v1/specs/metis-media-runtime-tiers.md
  • docs/releases/v1/specs/metis-voice-likeness-consent-record-contract.md
  • docs/releases/v1/reports/metis-v1-scorecard.md
  • docs/releases/v1/specs/todos.md
  • services/metis/src/metis/services/admin_service.py
  • libs/aja/avatar-library/src/types.ts
  • libs/aja/consent-management/src/types.ts

1. Purpose#

This document defines the canonical AvatarTeacherProfile contract for Metis V1.

Metis already has admin review queues for avatar teacher profiles, but the current implementation only infers them from generic Aja avatar-library types and review labels. That is insufficient for launch-grade governance because Metis needs an explicit object that binds:

  • teacher-facing identity and archetype
  • allowed Metis product tiers and runtime tiers
  • preview and release posture
  • linked likeness and voice approvals
  • learner-facing disclosure and safety posture

AvatarTeacherProfile is the Metis-owned representation of a learner-facing embodied teacher, not the underlying generic avatar asset.

2. Contract Role in the Metis Media Stack#

Order of responsibility:

  1. Aja owns generic avatar asset and customization primitives.
  2. Psyche owns realtime embodiment and avatar-session runtime.
  3. Metis owns the teacher-profile object that decides whether a specific avatar can appear as a teacher in educational flows.
  4. Publication, moderation, and incident workflows consume the Metis profile contract rather than raw avatar-library rows.

Rule:

  • A reusable avatar asset must not become learner-facing in Metis until an AvatarTeacherProfile exists and is release-approved.

3. Canonical Contract#

3.1 Identity#

ts
type AvatarTeacherProfileId = `atp_${string}`;
type AvatarTeacherProfileVersionId = `atpv_${string}`;
type LibraryAvatarRefId = string;
type VoicePackRefId = string;
type LikenessConsentRecordRefId = string;

3.2 Top-Level Shape#

ts
interface AvatarTeacherProfile {
  id: AvatarTeacherProfileId;
  versionId: AvatarTeacherProfileVersionId;
  teacherIdentity: AvatarTeacherIdentity;
  avatarRef: AvatarTeacherAvatarRef;
  teachingPosture: AvatarTeacherPosture;
  mediaPolicy: AvatarTeacherMediaPolicy;
  governance: AvatarTeacherGovernance;
  release: AvatarTeacherRelease;
  createdAt: string;
  updatedAt: string;
}

3.3 Teacher Identity#

ts
interface AvatarTeacherIdentity {
  displayName: string;
  internalName: string;
  teacherArchetype:
    | 'seminar_instructor'
    | 'skills_coach'
    | 'calm_guide'
    | 'exam_proctor'
    | 'office_hours_host';
  subjectDomains: string[];
  biography: string | null;
  localeDefault: string;
}

3.4 Avatar Reference#

ts
interface AvatarTeacherAvatarRef {
  libraryAvatarId: LibraryAvatarRefId;
  libraryVariant: string | null;
  previewImageUrls: string[];
  previewVideoUrl: string | null;
  thumbnailUrl: string | null;
  embodimentMode: 'full_avatar' | 'waist_up' | 'portrait';
  sourceOfRecord: 'aja_avatar_library';
}

Reference rule:

  • previewVideoUrl is required for learner-facing review and launch release.
  • sourceOfRecord must remain aja_avatar_library; Metis does not replace the underlying avatar asset registry.

3.5 Teaching Posture#

ts
interface AvatarTeacherPosture {
  teachingStyle:
    | 'demonstration_first'
    | 'guided_instruction'
    | 'coaching'
    | 'reflective'
    | 'office_hours';
  tone: 'warm' | 'professional' | 'encouraging' | 'calm' | 'high_structure';
  suitableLearnerContexts: (
    | 'independent_adult'
    | 'minor_supervised'
    | 'managed_program'
    | 'high_stakes_review'
  )[];
  prohibitedContexts: ('medical' | 'legal' | 'financial' | 'unguarded_minor')[];
  disclosureLabel: string;
}

3.6 Media Policy#

ts
interface AvatarTeacherMediaPolicy {
  allowedProductTiers: ('live_avatar_tutor' | 'prerecorded_lecturer')[];
  canonicalRuntimeTier: 'realtime_avatar_session';
  fallbackVoicePackId: VoicePackRefId | null;
  fallbackToVoiceAllowed: boolean;
  captionsRequired: boolean;
  transcriptRequired: boolean;
  multilingualDubbingAllowed: boolean;
}

Media-policy rule:

  • canonicalRuntimeTier must remain realtime_avatar_session.
  • A profile may allow prerecorded rendering, but it may not claim live_voice_tutor as its primary product tier.

3.7 Governance#

ts
interface AvatarTeacherGovernance {
  likenessConsentRecordIds: LikenessConsentRecordRefId[];
  voicePackIds: VoicePackRefId[];
  safetyReviewRequired: boolean;
  embodimentReviewRequired: boolean;
  disclosureReviewRequired: boolean;
  auditTrailRequired: boolean;
}

Governance rule:

  • likenessConsentRecordIds must be non-empty for any profile derived from or resembling a real person.
  • voicePackIds may be empty if the profile ships without an attached voice, but a live avatar session must not use a voice pack outside this allow-list.

3.8 Release#

ts
interface AvatarTeacherRelease {
  status:
    | 'draft'
    | 'review'
    | 'approved'
    | 'restricted'
    | 'revoked'
    | 'retired';
  releaseBlockers: string[];
  approvedBy: string | null;
  approvedAt: string | null;
  revokedAt: string | null;
  revocationReason: string | null;
}

4. Required Invariants#

The contract is invalid if any of the following are false:

  1. mediaPolicy.canonicalRuntimeTier === 'realtime_avatar_session'.
  2. avatarRef.libraryAvatarId is non-empty and resolves to an Aja library avatar.
  3. avatarRef.previewImageUrls.length >= 1.
  4. If release.status === 'approved', avatarRef.previewVideoUrl must be non-null.
  5. If release.status === 'approved', all release.releaseBlockers must be empty.
  6. If mediaPolicy.fallbackToVoiceAllowed === true, mediaPolicy.fallbackVoicePackId must be non-null.
  7. If teachingPosture.suitableLearnerContexts includes minor_supervised, teachingPosture.prohibitedContexts must still include unguarded_minor.
  8. If the profile is likeness-based, governance.likenessConsentRecordIds must be non-empty before release.status may become approved.

5. Mapping to Existing Runtime Truth#

AvatarTeacherProfile formalizes seams that already exist in the codebase:

AvatarTeacherProfile field Existing seam
avatarRef.libraryAvatarId, preview assets, and avatar archetype signals libs/aja/avatar-library/src/types.ts
teachingPosture.* and profile naming expectations Metis admin review heuristics in services/metis/src/metis/services/admin_service.py
mediaPolicy.allowedProductTiers and canonical runtime split docs/releases/v1/specs/metis-media-runtime-tiers.md
governance.voicePackIds and release blockers voice-pack and likeness-consent review queues already derived in admin_service.py
release.status, releaseBlockers, and operator review requirements Metis admin review queue state and audit workflows

6. Consumer Rules#

6.1 Admin Review#

The Metis admin review queue for avatar_teacher_profile should resolve into AvatarTeacherProfile.release and AvatarTeacherProfile.governance. Queue rows are review projections, not the source of record.

6.2 Runtime Bring-Up#

Live avatar runtime provisioning must select one approved AvatarTeacherProfile. It must not mount an arbitrary Aja avatar directly.

6.3 Learner Disclosure#

Learner-facing disclosure should derive from teachingPosture.disclosureLabel plus runtime disclosure rules, not from freeform page copy.

7. Ownership Boundary#

Metis owns:

  • teacher-profile identity
  • educational posture and learner-context policy
  • release and review posture
  • linkage to consent and voice governance

Aja owns:

  • generic avatar asset definitions
  • asset variants and preview artifacts

Psyche owns:

  • realtime avatar transport and rendering runtime
  • low-level embodiment controls

8. Implementation Direction#

V1-MET-090 is complete when future Metis code and review flows use this contract name and shape instead of inferring “teacher profile” from generic Aja avatar categories alone.