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.mddocs/releases/v1/specs/metis-voice-likeness-consent-record-contract.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/specs/todos.mdservices/metis/src/metis/services/admin_service.pylibs/aja/avatar-library/src/types.tslibs/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:
- Aja owns generic avatar asset and customization primitives.
- Psyche owns realtime embodiment and avatar-session runtime.
- Metis owns the teacher-profile object that decides whether a specific avatar can appear as a teacher in educational flows.
- 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
AvatarTeacherProfileexists and is release-approved.
3. Canonical Contract#
3.1 Identity#
type AvatarTeacherProfileId = `atp_${string}`;
type AvatarTeacherProfileVersionId = `atpv_${string}`;
type LibraryAvatarRefId = string;
type VoicePackRefId = string;
type LikenessConsentRecordRefId = string;
3.2 Top-Level Shape#
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#
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#
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:
previewVideoUrlis required for learner-facing review and launch release.sourceOfRecordmust remainaja_avatar_library; Metis does not replace the underlying avatar asset registry.
3.5 Teaching Posture#
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#
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:
canonicalRuntimeTiermust remainrealtime_avatar_session.- A profile may allow prerecorded rendering, but it may not claim
live_voice_tutoras its primary product tier.
3.7 Governance#
interface AvatarTeacherGovernance {
likenessConsentRecordIds: LikenessConsentRecordRefId[];
voicePackIds: VoicePackRefId[];
safetyReviewRequired: boolean;
embodimentReviewRequired: boolean;
disclosureReviewRequired: boolean;
auditTrailRequired: boolean;
}
Governance rule:
likenessConsentRecordIdsmust be non-empty for any profile derived from or resembling a real person.voicePackIdsmay 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#
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:
mediaPolicy.canonicalRuntimeTier === 'realtime_avatar_session'.avatarRef.libraryAvatarIdis non-empty and resolves to an Aja library avatar.avatarRef.previewImageUrls.length >= 1.- If
release.status === 'approved',avatarRef.previewVideoUrlmust be non-null. - If
release.status === 'approved', allrelease.releaseBlockersmust be empty. - If
mediaPolicy.fallbackToVoiceAllowed === true,mediaPolicy.fallbackVoicePackIdmust be non-null. - If
teachingPosture.suitableLearnerContextsincludesminor_supervised,teachingPosture.prohibitedContextsmust still includeunguarded_minor. - If the profile is likeness-based,
governance.likenessConsentRecordIdsmust be non-empty beforerelease.statusmay becomeapproved.
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.