# OSHUN V1 Metis `AvatarTeacherProfile` Contract

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.
