Forge · Kagami Character Generation

01

System Architecture

ForgeService orchestrates the complete character generation pipeline from text prompt to exportable 3D assets.

✓ VERIFIED LOC COUNTS (wc -l)

service.py:      610 LOC    schema.py:       754 LOC    safety.py:        121 LOC
orchestrator.py: 368 LOC    streaming.py:    129 LOC    rooms_export.py: 1,128 LOC
visual_design/:  3,214 LOC  motion/:        3,861 LOC   behavior_ai/:    1,472 LOC
export/:         3,112 LOC  conversation/:  1,930 LOC   TOTAL:          34,689 LOC

packages/kagami/forge/

02

Generation Pipeline

8-stage pipeline from text concept to exportable 3D character.

📝 Concept

→

🎨 Visual

→

🦴 Rigging

→

🎬 Animation

→

🧠 Personality

→

🌍 World

→

📦 Export

Stage	Module	Key File	LOC
1. Visual Design	`modules/visual_design/`	character_profiler.py	3,214
2. Rigging	`modules/rigging/`	UniRig skeleton binding	—
3. Animation	`modules/motion/`	facial_animator.py (1,065 LOC)	3,861
4. Personality	`modules/behavior_ai/`	personality_engine.py (724 LOC)	1,472
5. Voice	`modules/voice/`	TTS profile generation	—
6. Narrative	`backstory_synthesizer`	Backstory, motivations	—
7. World	`modules/world/`	Scene composition	—
8. Export	`modules/export/`	8 format exporters	3,112

# VERIFIED: Direct from kagami.forge.__init__.py
from kagami.forge import (
    ForgeService,
    ForgeOperation,
    ForgeRequest,
    ForgeResponse,
    get_forge_service,
)

# ForgeOperation enum (service.py:43-57)
ForgeOperation.CHARACTER_GENERATION   # "character.generate"
ForgeOperation.IMAGE_TO_CHARACTER     # "character.from_image"
ForgeOperation.ANIMATION_FACIAL       # "animation.facial"
ForgeOperation.ANIMATION_GESTURE      # "animation.gesture"
ForgeOperation.ANIMATION_MOTION       # "animation.motion"
ForgeOperation.GENESIS_VIDEO          # "genesis.video"
ForgeOperation.VALIDATION             # "validation"
ForgeOperation.CONTENT_SAFETY         # "content_safety"

# Usage
service = get_forge_service()
result = await service.generate_character(
    concept="warrior princess",
    quality_mode="draft",  # "preview" | "draft" | "final"
)

03

Core Modules

111 Python files organized by capability.

Service Layer

⚡

ForgeService

forge/service.py

Unified entry point. Abstracts ForgeMatrix, handles request standardization, metrics, semantic caching.

610

LOC ✓

8

Operations

APIAsync

🎯

ForgeMatrix

forge/matrix/orchestrator.py

Pipeline orchestrator. ComponentRegistry tracks generation modules. Coordinates stage execution.

368

LOC ✓

8

Stages

Orchestrator

🛡️

SafetyGate

forge/safety.py

Content safety. Ethical check, threat detection. Fails closed — violations never pass.

121

LOC ✓

Safety

📊

Schema

forge/schema.py

Data structures: Character, Mesh, Skeleton, Animation, VoiceProfile, PersonalityProfile, QualityMetrics.

754

LOC ✓

50+

Types

TypesDataclass

Generation Modules

🎨

Visual Design

forge/modules/visual_design/

Text-to-3D mesh generation. CharacterVisualProfiler analyzes concepts.

6

Files

3,214

LOC ✓

3DML

🎬

Motion

forge/modules/motion/

FacialAnimator with 50+ blendshapes. GestureEngine for body language. MotionRetargeting.

9

Files

3,861

LOC ✓

AnimationPyTorch

🧠

Personality Engine

forge/modules/behavior_ai/

Big Five personality generation. Six archetypes: Analytical, Expressive, Driving, Amiable, Creative, Guardian.

4

Files

1,472

LOC ✓

LLMAI

📦

Export Manager

forge/modules/export/

8 format exporters: FBX, GLTF, USD, OBJ, DAE, PLY, STL, X3D. Materials and animations included.

12

Files

3,112

LOC ✓

ExportAsync

Integration Modules

💬

Conversation

forge/modules/conversation/

ForgeConversationManager, RealtimeRoomStreamer, SmartHomeRoomMapper. Room-aware audio routing.

6

Files

1,930

LOC ✓

AudioRealtime

🔗

Rooms Export

forge/rooms_export.py

CRDT-based export to multiplayer Rooms. HybridLogicalClock, LWW-Register for conflict-free updates.

1,128

LOC ✓

CRDT

Sync

CRDTMultiplayer

📡

Streaming

forge/streaming.py

StreamingGenerator yields ProgressUpdate with stage, percent, message, preview_url, eta_seconds.

129

LOC ✓

AsyncGenerator

04

Rooms Integration

Export characters to multiplayer environments with CRDT sync.

# VERIFIED: from kagami.forge import ForgeRoomsExporter
from kagami.forge import ForgeRoomsExporter

exporter = ForgeRoomsExporter()

# Export with CRDT semantics (rooms_export.py)
success = await exporter.export_character_to_room(
    room_id="gallery_01",
    character_data={
        "id": "warrior_01",
        "gltf_url": "https://cdn.example.com/warrior.glb",
    },
    position=[5.0, 0.0, -3.0],
)

# CRDT guarantees: Commutative, Associative, Idempotent

05

API Reference

REST endpoints from kagami_api/routes/command/forge/

✓ VERIFIED ROUTES (from __init__.py)

kagami_api/routes/command/forge/
├── generate.py          POST /generate
├── animate.py           POST /animate/*
├── validate.py          POST /validate
├── intent.py            POST /intent
├── image_generation.py  POST /image/*
└── content_safety.py    POST /safety/*

🌐

REST Endpoints

/api/command/forge/

FastAPI routes for character generation, animation, validation.

POST /generate     # Character
POST /animate/*    # Animation
POST /validate     # Validation
POST /intent       # Intent parsing
POST /image/*      # Image gen
POST /safety/*     # Safety check

⚙️

Quality Levels

schema.py:100-107

QualityLevel enum from schema.

# Verified from schema.py
LOW    = "low"
MEDIUM = "medium"
HIGH   = "high"
ULTRA  = "ultra"
CUSTOM = "custom"

📋

Export Formats

schema.py:73-84

ExportFormat enum from schema.

# Verified from schema.py
FBX  GLTF  GLB  USD
OBJ  DAE   BLEND
MAX  MAYA

📁

Export Modules

modules/export/

Actual exporter implementations.

# 12 files in export/
fbx_exporter.py
gltf_exporter.py
usd_exporter.py
obj_exporter.py
dae_exporter.py
ply_exporter.py
stl_exporter.py
x3d_exporter.py