scriba-ai 0.4.0

Scriba — Video knowledge workbench (V1 local GPU + V2 BYOK API)

Scriba

Video & Document knowledge workbench — 영상·오디오·문서·웹페이지를 화자 분리된 스크립트, 챕터별 요약, RAG Q&A, 문제집·프레젠테이션·마케팅 자료로 자동 변환하는 플랫폼.

---

✨ 한눈에

Scriba (라틴어 필경사)는 영상→지식 자산 변환 플랫폼입니다.

1시간짜리 회의·강의·인터뷰·강연·PDF·웹 아티클을 입력하면:

• 화자별 정리된 스크립트 + 원본/정제본 분리
• 챕터별 AI 요약 (6가지 종류 자동 분류)
• 출처가 명시된 Q&A (🟢인용/🟡추론/⚠️추정 3색 라벨)
• 문제집 (Bloom's Taxonomy 6단계) / 프레젠테이션 (PPTX+Marp) / 마케팅 자료 (8종)
• REST API + MCP 서버 (Claude Code 등 AI 에이전트와 직접 연동)

---

🏗️ 아키텍처

입력 (영상·음성·PDF·URL·MD·TXT)
  │
  ├─ 영상/음성 → FFmpeg → STT (로컬 Whisper OR Azure Whisper) → pyannote 화자분리
  └─ 문서/웹   → 어댑터 (페이지/섹션 구조 보존)
                     │
                     ▼
              Merger (화자+텍스트 정렬)
                     │
              Chapterizer (영상=시간 기반 / 문서=구조 기반)
                     │
              Summarizer (Map-Reduce, 소스 타입별 프롬프트 분기)
                     │
        ┌────────────┼────────────────┐
        ▼            ▼                ▼
   transcript    summary.json    RAG Index
   (.md/.srt)   (magazine.md)  (BM25+embedding)
        │
        └─ Content Remix Engine
               ├─ 문제집 (PDF, Bloom 6단계)
               ├─ 프레젠테이션 (PPTX + Marp)
               └─ 마케팅 자료 (8종 × 5페르소나 × 4톤)

---

🎯 주요 기능

기능	설명
이중 STT	로컬 faster-whisper large-v3 (GPU) 또는 Azure Whisper API (클라우드, GPU 불필요)
화자 분리	pyannote 3.1 (로컬) 또는 AssemblyAI/Deepgram 내장. UI에서 단일/다중 선택
소스 타입 분리	영상=타임스탬프, PDF=페이지 참조, 웹=섹션 제목, MD=헤딩 기반 출력
Map-Reduce 요약	챕터 6종(procedure/concept/narrative/discussion/demo/mixed) 자동 분류
원문 인용 보장	key_quotes verbatim 검증, Executive Summary 수치 의무화
Content Remix	Bloom 6단계 문제집(PDF) · PPTX/Marp 프레젠테이션 · 마케팅 자료 8종
REST API	FastAPI 11개 엔드포인트 (포트 8000) + OpenAPI 문서
MCP 서버	10개 Tool — Claude Code 등 AI 에이전트에서 직접 호출
Python SDK	from sdk import Scriba — REST API 완전 커버
Hybrid RAG	BM25(CJK bigram) + 임베딩 RRF 융합, Cross-run 검색
SaaS 인프라	사용자/API 키/미터링/멀티테넌시 경로 분리

---

📁 모듈 구조

src/
├── pipeline_v2.py       ← V2 파이프라인 (BYOK 백엔드 선택)
├── adapters/            ← mp4·mp3·pdf·md·txt·srt·url 어댑터 (소스 타입 판별)
├── stt/                 ← STT 백엔드 (local_whisper·openai·azure_whisper·deepgram·assemblyai)
├── chapterizer.py       ← 시간/구조/페이지 기반 챕터 분할
├── summarizer.py        ← Map-Reduce + 소스 타입별 프롬프트
├── exporter.py          ← md/srt/json/ics/zip + page_ref 기반 출력
├── remix/               ← Content Remix Engine (quiz_pro·presentation·marketing)
├── metering.py          ← 플랜별 사용량 한도
├── db.py                ← SQLite (users·api_keys·usage_events·runs 등)
└── email_service.py     ← SMTP 이메일 알림

app/
├── api.py               ← FastAPI REST API (포트 8000)
├── api_users.py         ← 회원가입/API 키 관리
├── mcp_server.py        ← MCP 서버 (stdio/SSE)
├── web.py               ← Gradio Web UI (포트 7860)
└── cli.py               ← CLI (vts web / vts api / vts mcp)

sdk/
└── client.py            ← Python SDK (scriba-client)

---

🚀 빠른 시작

# 1. 환경 설정
conda activate vod-script

# 2. 환경 변수
copy .env.example .env   # Azure OpenAI / Whisper / HF 토큰 입력

# 3. Web UI
vts web         # http://127.0.0.1:7860

# 4. REST API
vts api         # http://127.0.0.1:8000 · /docs

# 5. MCP (Claude Code 연동)
vts mcp

Docker Compose (서버 배포)

docker compose up -d     # web(7860) + api(8000) 동시 기동

---

🔌 REST API / MCP

# API 키 발급
curl -X POST http://localhost:8000/api/v1/auth/register \
  -d '{"email":"[e-mail]","plan":"free"}'

# 파일 처리
curl -X POST http://localhost:8000/api/v1/process \
  -H "Authorization: Bearer sk-scriba-xxx" \
  -d '{"file_path":"/path/to/meeting.mp4"}'

Python SDK

from sdk import Scriba

client = Scriba(api_key="sk-scriba-xxx")
run = client.process("meeting.mp4", speakers="auto", lang="ko")
summary = client.get_summary(run.run_id)
pptx = client.generate_presentation(run.run_id, style="exec_brief")

Claude Code MCP 설정 (.mcp.json)

{
  "mcpServers": {
    "scriba": {
      "command": "conda",
      "args": ["run", "-n", "vod-script", "--no-capture-output", "vts", "mcp"],
      "cwd": "D:\\VOD-to-Script"
    }
  }
}

---

📋 요구사항

항목	내용
OS	Windows 11 (Primary) / Linux (Docker)
Python	3.11 (conda)
GPU	NVIDIA CUDA 12.x, VRAM 8GB+ (로컬 STT·화자분리 시)
Azure OpenAI	GPT-4.1-mini + Whisper 배포
HuggingFace	pyannote 3.1 약관 동의 토큰

---

📦 출력 파일

파일	설명
transcript.md	소스 타입별 포맷 (영상=타임스탬프, 문서=페이지/섹션 참조)
transcript_raw.md	STT 원본 (정제 전)
transcript.srt	영상 자막
summary.json	구조화 요약
summary_magazine.md	인사이트 레이어 (Executive Summary·핵심 인사이트)
schedule.ics/.md/.json	일정·액션 아이템
quiz.*	Bloom 6단계 문제집
result.zip	전체 묶음

---

🧪 테스트

pytest -q   # 415 passed

---

📚 문서

• MASTER_PLAN_2026.md — 전체 작업 계획 + 완료 현황
• HANDOVER_2026-05-18.md — 최신 핸드오버
• ROADMAP_v5.md — 플랫폼화 + 사업화 로드맵
• BUSINESS_PLAN.md — 사업 계획

---

🛡️ 프라이버시

• 원본 영상·오디오는 로컬에서만 처리 (로컬 STT 선택 시)
• 외부 전송: Azure OpenAI에 텍스트만 (Azure Whisper 선택 시 오디오 청크 전송)
• Web UI 기본 바인딩: 127.0.0.1
• API 키는 .env로만 주입

---

📄 라이선스

MIT