Sri01729/template-ai-storyboard-consistent-character: 일관된 캐릭터 생성을 지원하는 AI 스토리보드

Mastra로 구축된 포괄적인 AI 기반 스토리보드 생성 시스템으로, 일관된 캐릭터 생성 (consistent character generation) 및 고급 평가 지표를 통해 스토리보드를 생성, 개선 및 내보내는 데 특화된 여러 전문 에이전트(Agent)를 특징으로 합니다. 이 템플릿은 에이전트 네트워크 (Agent Networks), 자동화된 워크플로 (Automated Workflows), 메모리 관리 (Memory Management) 및 포괄적인 평가 시스템을 포함한 고급 Mastra 기능을 보여줍니다.

멀티 에이전트 아키텍처 (Multi-Agent Architecture): 협업하는 5개의 전문 에이전트
에이전트 네트워크 (Agent Networks): 조정된 에이전트 간 통신 및 작업 분배
자동화된 워크플로 (Automated Workflows): 엔드 투 엔드 (End-to-end) 스토리보드 생성 파이프라인
메모리 관리 (Memory Management): LibSQL 스토리지를 활용한 지속적인 에이전트 메모리
MCP 통합 (MCP Integration): 외부 도구 통합을 위한 모델 컨텍스트 프로토콜 (Model Context Protocol)
포괄적 평가 (Comprehensive Evaluation): 11개의 맞춤형 지표 구현 (스토리보드 5개 + 스크립트 5개 + 비전 기반 이미지 일관성 1개)

Google Drive 업로드: Zapier 웹훅 (Webhooks)을 통한 직접 파일 업로드
AWS S3 통합: 생성된 PDF를 위한 클라우드 스토리지
Slack 알림: 실시간 상태 업데이트
다중 AI 제공업체: OpenAI 및 Google Gemini 지원

AI 기반 스토리보드 생성: 텍스트 설명을 통해 완전한 스토리보드 생성
멀티 에이전트 아키텍처 (Multi-Agent Architecture): 스토리보드 생성의 다양한 측면을 위한 전문 에이전트
스크립트 생성 (Script Generation): 스토리보드를 대사가 포함된 상세 스크립트로 변환
이미지 생성 (Image Generation): 스토리보드 장면을 위한 시각적 프롬프트 생성
내보내기 기능 (Export Capabilities): PDF 형식
PDF 업로드 및 처리: Google Drive 통합을 통해 PDF에서 스토리보드 데이터 추출 및 처리

TypeScript: 완전한 타입 안정성 (Full type safety) 및 현대적인 개발 경험
Mastra Framework: 강력한 Mastra AI 프레임워크를 기반으로 구축
AI SDK Integration: 다양한 AI 제공업체 (OpenAI, Google Gemini) 지원
Modular Architecture: 전용 모듈을 통한 깔끔한 관심사 분리 (Separation of concerns)
Comprehensive Evaluation System: 모든 에이전트에 대한 품질 지표 (Quality metrics)
Google Drive Integration: Google Drive로의 직접적인 파일 업로드
Slack Notifications: Zapier 웹훅 (webhooks)을 통한 실시간 알림

목적 (Purpose): 스토리 설명을 바탕으로 완전한 스토리보드 생성
기능 (Capabilities): 장면 분할 (Scene breakdown), 시각적 묘사, 캐릭터 개발
평가 (Evaluation): 구조 검증, 시각적 프롬프트 품질, 콘텐츠 완성도

목적 (Purpose): 스토리보드를 대사가 포함된 상세 스크립트로 변환
기능 (Capabilities): 대사 생성, 캐릭터 음성, 장면 전환
평가 (Evaluation): 스크립트 구조, 대사 품질, 캐릭터 개발

목적 (Purpose): 스토리보드 장면을 위한 시각적 프롬프트를 생성하고 이미지를 생성
기능 (Capabilities): 장면 시각화, 스타일 일관성, 기술적 사양, Google Imagen 통합
평가 (Evaluation): GPT-4o-mini vision 기능을 사용한 캐릭터 및 환경의 시각적 일관성 분석

목적 (Purpose): 내보내기 및 데이터 정리 처리
기능 (Capabilities): PDF 내보내기, 데이터 포맷팅, 파일 생성

목적 (Purpose): 클라우드 통합을 통해 업로드된 PDF에서 데이터를 처리 및 추출
기능 (Capabilities): PDF 파싱, 콘텐츠 추출, 데이터 변환, Google Drive 업로드, Slack 알림
통합 (Integrations):
Google Drive: 지정된 폴더로의 직접 파일 업로드
Slack: 업로드 상태 및 처리 결과에 대한 Zapier 웹훅을 통한 실시간 알림

이 프로젝트는 고품질의 결과물을 보장하기 위해 Mastra Evals를 기반으로 구축된 종합적인 평가 시스템을 포함합니다:

11가지 커스텀 지표 구현: 스토리보드, 스크립트 및 이미지 에이전트를 위한 특화된 평가 기준
멀티모달 평가 (Multi-Modal Evaluation): GPT-4o-mini를 사용한 이미지 일관성 기반의 비전 분석
휴리스틱 + LLM 기반: 효율적인 규칙 기반 평가와 고급 비전 분석의 결합
상세 로깅 (Detailed Logging): 포괄적인 디버깅 및 투명성 제공
JSON 추출 (JSON Extraction): 마크다운으로 감싸진 JSON 출력을 자동으로 처리

구조 검증 (Structure Validation): 적절한 JSON 형식 및 필수 필드 보장
콘텐츠 분석 (Content Analysis): 품질, 완성도 및 일관성 평가
성능 추적 (Performance Tracking): 시간에 따른 에이전트 성능 모니터링

스토리보드 에이전트 (Storyboard Agent): 5가지 지표 (구조, 시각적 품질, 콘텐츠 완성도, 캐릭터 일관성, 서사 흐름)
스크립트 에이전트 (Script Agent): 5가지 지표 (구조, 대사 품질, 캐릭터 발전, 플롯 일관성, 장르 부합성)
이미지 생성 에이전트 (Image Generator Agent): 1가지 비전 기반 지표 (가중치 점수를 적용한 캐릭터 및 환경의 시각적 일관성)

@mastra/core: AI 에이전트 개발을 위한 핵심 Mastra 프레임워크
@mastra/evals: 품질 지표를 위한 평가 시스템
@mastra/libsql: 에이전트 메모리를 위한 LibSQL 저장소
@mastra/loggers: 디버깅 및 모니터링을 위한 로깅 시스템
@mastra/memory: 에이전트 상태를 위한 메모리 관리
@ai-sdk/google: Gemini 모델을 위한 Google AI 통합
@ai-sdk/openai: 콘텐츠 분석 및 생성을 위한 OpenAI 통합
@aws-sdk/client-s3: PDF 업로드를 위한 AWS S3 클라우드 저장소
@aws-sdk/s3-request-presigner: S3 사전 서명된 URL (Presigned URL) 생성
@google/genai: 이미지 생성을 위한 Google Generative AI
@google/generative-ai: 고급 기능을 위한 Google AI SDK
@modelcontextprotocol/server-filesystem: MCP 파일 시스템 서버 통합
canvas: 이미지 처리를 위한 Canvas API
jspdf: PDF 생성 라이브러리
pdfkit: PDF 생성 및 조작
zod: 스키마 검증 및 타입 안정성

• Node.js 18 이상
• npm 또는 yarn 패키지 매니저
• OpenAI 및 Google Gemini API 키

# 저장소 복제 (Clone the repository)
git clone <repository-url>
cd AI-Story-Board-Generator
...

src/mastra/
├── agents/ # 5개의 특화된 AI 에이전트 (AI agents)
├── tools/ # 처리를 위한 6개의 커스텀 도구 (custom tools)
...

# 필수 API 키 (Required API Keys)
OPENAI_API_KEY=your_openai_key # 메모리 내 임베딩 (embeddings)에 사용됨
GOOGLE_API_KEY=your_google_key # Google/Gemini 모델에서 사용됨
...

플레이그라운드 (playground)에서 다양한 서브 에이전트 (subagents)에 접근하여 개별적으로 실험해 볼 수 있습니다:

스토리보드 에이전트 (Storyboard Agent): 스크립트 (scripts)로부터 시각적 스토리보드를 생성합니다
스크립트 생성 에이전트 (Script Generator Agent): 스토리 아이디어를 상세한 시나리오 (screenplays)로 변환합니다
이미지 생성 에이전트 (Image Generator Agent): 스토리보드 장면을 위한 이미지를 생성합니다
내보내기 에이전트 (Export Agent): PDF 및 기타 내보내기 형식 (export formats)을 생성합니다
PDF 업로드 에이전트 (PDF Upload Agent): S3 및 Google Drive로의 클라우드 업로드를 처리합니다

조정된 멀티 에이전트 워크플로 (multi-agent workflows)를 위해서는 플레이그라운드 채팅 인터페이스에서 v-next 스트림 에이전트 네트워크 (stream agent network)를 사용하세요:

프롬프트 구조 (Prompt Structure):

"따뜻한 일출 톤, 스팀펑크 스타일의 디테일, 그리고 감동적인 경이로움을 담은 스팀펑크 스타일로, '등불이 떠다니는 마을에 살며 새벽에 기계 새와 함께 마을의 잃어버린 빛을 찾아 떠나는 호기심 많은 소년'의 이야기를 위한 스토리보드를 만들어줘. 최종 비주얼을 PDF로 컴파일하여 내 드라이브에 업로드해줘"

네트워크는 자동으로 다음을 수행합니다:

• 스토리 아이디어로부터 스크립트 생성
• 스크립트를 장면이 포함된 스토리보드로 변환
• 각 장면에 대한 이미지 생성
• 이미지가 포함된 PDF 생성
• S3 및 Google Drive로 업로드

스토리보드에 사용할 스타일을 다음 중에서 선택하세요:

Cinematic (시네마틱): 사진 같은 품질을 가진 전문적인 영화 스틸컷
Photographic (사진적): 자연스러운 조명이 포함된 고품질 사진
Anime (애니메이션): 셀 셰이딩 (cel-shaded) 캐릭터가 포함된 활기찬 애니메이션 스타일
Manga (만화): 스크린톤 (screentones)이 포함된 흑백 만화 패널
Ghibli-esque (지브리 스타일): 기발한 손그림 애니메이션 스타일
Disney-esque (디즈니 스타일): 표현력이 풍부한 캐릭터가 등장하는 클래식 디즈니 애니메이션
Comic Book (코믹북): 굵은 윤곽선이 특징인 미국 코믹북 아트
Graphic Novel (그래픽 노블): 분위기 있는 조명이 특징인 성숙한 그래픽 노블 스타일
Watercolor (수채화): 부드러운 경계선을 가진 아름다운 수채화
Low Poly (로우 폴리): 기하학적 모양을 가진 3D 로우 폴리 (low poly) 렌더링
Pixel Art (픽셀 아트): 향수를 불러일으키는 레트로 미학을 가진 16비트 픽셀 아트
Steampunk (스팀펑크): 황동 디테일이 포함된 빅토리아 시대 스팀펑크 스타일
Cyberpunk (사이버펑크): 네온 빛이 가득한 사이버펑크 도시 경관
Fantasy Art (판타지 아트): 극적인 조명이 포함된 서사적인 판타지 아트
Film Noir (필름 누아르): 대비가 강한 흑백 필름 누아르

import { mastra } from './src/mastra';
// 스토리보드 생성
const storyboardAgent = mastra.getAgent('storyboardAgent');
...

import { generateAndUploadStoryboard } from './src/mastra';
const result = await generateAndUploadStoryboard({
storyIdea: '한 젊은 여성이 오래된 도서관에서 마법의 책을 발견합니다.',
...

import { storyboardSpecificEvals } from './src/mastra/evals/storyboard-evals';
// 스토리보드 품질 평가
const result = await storyboardSpecificEvals.structure.measure(
...

# 직접적인 평가 (evals) 예제 실행
npx tsx examples/evals.ts

src/
├── mastra/
│ ├── agents/ # AI 에이전트 구현체
...

모든 평가 지표는 0.0에서 1.0 사이의 점수를 반환합니다:

0.9-1.0: 매우 우수한 품질, 기대치를 초과함
0.7-0.8: 좋은 품질, 대부분의 요구 사항을 충족함
0.4-0.6: 허용 가능한 품질, 약간의 개선 필요
0.0-0.3: 낮은 품질, 상당한 개선 필요

npm run dev # 개발 서버 시작
npm run build # 프로젝트 빌드

메모리 관리 (Memory Management): 영구적인 에이전트 메모리를 위해 LibSQL 사용
에이전트 네트워크 (Agent Networks): 에이전트 간 효율적인 작업 분배
스트리밍 (Streaming): 더 나은 UX를 위한 실시간 출력 스트리밍
캐싱 (Caching): 생성된 콘텐츠의 지능형 캐싱

API 키 관리 (API Key Management): 안전한 환경 변수 처리
입력 검증 (Input Validation): 포괄적인 Zod 스키마 검증
에러 핸들링 (Error Handling): 유연한 에러 처리 및 로깅
액세스 제어 (Access Control): 외부 서비스에 대한 적절한 인증

1. API 키 에러

# 환경 변수 확인
echo $OPENAI_API_KEY
echo $GOOGLE_API_KEY
...

2. 메모리 데이터베이스 문제

# 메모리 데이터베이스 초기화
rm mastra-memory.db
npm run dev

3. 평가 실패 (Evaluation Failures)

# 특정 지표 디버깅
npx tsx examples/evals.ts

4. PDF 업로드 문제

# AWS 자격 증명 확인
aws sts get-caller-identity
# Zapier 웹훅 확인
...

• 실시간 피드백을 위해 streaming 함수를 사용하세요
• 일관된 캐릭터 발전을 위해 메모리를 활성화하세요
• 복잡한 다단계 프로세스에는 에이전트 네트워크를 사용하세요
• 품질 향상을 위해 평가 점수를 모니터링하세요

// 스토리 아이디어로부터 전체 스토리보드 생성
const result = await generateCompleteStoryboard(
"A young detective solves a mystery in a small town",
...

// 스토리 아이디어로부터 스크립트 생성
const script = await generateScript(
"A romantic comedy about two chefs",
...

// 스토리보드용 이미지 생성
const images = await generateStoryboardImages(
storyboardData,
...

// PDF로 내보내기
const pdf = await exportStoryboard(
storyboardData,
...

// PDF 업로드 및 처리
const result = await generateAndUploadStoryboard(
storyboardData,
...

각 에이전트는 사용자 정의 설정으로 구성할 수 있습니다:

import { storyboardAgent } from './src/mastra/agents/storyboard-agent';
// 사용자 정의 에이전트 설정
const customAgent = new Agent({
...

import { createAgentMemory } from './src/mastra/memory-config';
// 메모리 인스턴스 생성
const memory = createAgentMemory();
...

import { storyboardSpecificEvals } from './src/mastra/evals/storyboard-evals';
// 평가 실행
const result = await storyboardSpecificEvals.structure.measure(
...

이 템플릿은 Mastra의 공식 템플릿 가이드라인을 따릅니다:

프로젝트 구조 (Project Structure): 모든 Mastra 코드는 src/mastra/에 위치

TypeScript: Zod 스키마를 사용한 엄격한 타이핑 (Strict typing)

ES Modules: `