Metadata-Version: 2.4
Name: scriba-ai
Version: 0.4.0
Summary: Scriba — Video knowledge workbench (V1 local GPU + V2 BYOK API)
Author-email: Park <ssdavo34@gmail.com>
License: MIT
Keywords: whisper,pyannote,stt,rag,obsidian,transcription
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Scriba

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

[![python](https://img.shields.io/badge/python-3.11-blue)](https://www.python.org/)
[![cuda](https://img.shields.io/badge/CUDA-12.x-green)](https://developer.nvidia.com/cuda-zone)
[![tests](https://img.shields.io/badge/tests-415%2F415-brightgreen)](#)
[![license](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)

---

## ✨ 한눈에

`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)
```

---

## 🚀 빠른 시작

```bash
# 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 (서버 배포)

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

---

## 🔌 REST API / MCP

```bash
# API 키 발급
curl -X POST http://localhost:8000/api/v1/auth/register \
  -d '{"email":"me@example.com","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

```python
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`)

```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` | 전체 묶음 |

---

## 🧪 테스트

```bash
pytest -q   # 415 passed
```

---

## 📚 문서

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

---

## 🛡️ 프라이버시

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

---

## 📄 라이선스

MIT
