feat(p1): scaffolding + Device Manager / VRAM probe + CLI detect

- pyproject (uv, src layout) + extras: engine/gpu/api/diarize/llm
- config.py (pydantic-settings, SCRIBE_ env)
- devices/: vram_probe (NVML/psutil/disk) + DeviceManager →
  capability tier T0–T3, precision by cc/VRAM, worker estimate (계획 §3.6, AC-2/3)
- cli.py (typer): detect (구현) + transcribe/bench/serve (스텁)
- run.sh, .env.example, README

Verified on GTX 1050/2GB: detect → T0_CPU (turbo doesn't fit → explicit
downgrade, fail-explicit). Overrides (--device/--workers) work. 7 unit tests
cover T0–T3 + overrides via synthetic VRAM. ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,24 @@
+# luke_scribe 설정 예시 — 복사: cp .env.example .env  (env prefix: SCRIBE_)
+
+# 모델 (하이브리드 기본; P1 bench 결과에 따라 단일 turbo로 통일 가능)
+SCRIBE_MODEL_REALTIME=large-v3-turbo
+SCRIBE_MODEL_BATCH=large-v3
+
+# 디바이스: auto|cpu|cuda|cuda:0 — 자동 산정, 강제 가능
+SCRIBE_DEVICE=auto
+# SCRIBE_COMPUTE_TYPE=int8        # 비우면 cc/VRAM 기반 자동
+# SCRIBE_WORKERS=1                # 비우면 자동 산정
+
+SCRIBE_LANGUAGE=ko
+
+# 입력 절대 상한 (초과 413)
+SCRIBE_MAX_DURATION_S=14400       # 4h
+SCRIBE_MAX_SIZE_BYTES=2147483648  # 2GB
+
+# 보관 (P2+)
+SCRIBE_RETENTION_DAYS=7
+# SCRIBE_REDIS_URL=redis://localhost:6379/0
+# SCRIBE_API_KEYS=["key1","key2"]
+
+# 터널 (P5): none|cloudflare|ngrok
+SCRIBE_TUNNEL=none

README.md

@@ -0,0 +1,26 @@
+# luke_scribe
+
+내부용 **로컬 STT 전사 API** — faster-whisper(CTranslate2) 기반, 하드웨어 적응형.
+단일 `Job` 추상화로 배치(파일/영상)와 실시간(WebSocket)을 처리한다.
+
+> 설계 단일 진실원본(SoT): [`.omc/plans/consensus-luke-scribe-stt-api.md`](.omc/plans/consensus-luke-scribe-stt-api.md),
+> [`.omc/specs/deep-interview-luke-scribe-stt-api.md`](.omc/specs/deep-interview-luke-scribe-stt-api.md)
+
+## 상태
+- 설계 완료(모호도 ~5%) · 구현 P1 진행 중 (greenfield).
+
+## 빠른 시작 (개발)
+```bash
+uv sync                       # 코어 의존성
+uv run luke-scribe detect     # 하드웨어 감지 → 능력등급/정밀도/워커수
+# 엔진(transcribe/bench)은 다음 증분:
+# uv sync --extra engine
+```
+
+## CLI
+| 명령 | 설명 | 상태 |
+|------|------|------|
+| `detect` | 하드웨어 감지·능력등급(T0~T3)·정밀도·워커수 | ✅ P1 |
+| `transcribe <file>` | 단발 파일 전사 | ⏳ P1 |
+| `bench` | turbo vs large-v3 도메인 벤치(게이트) | ⏳ P1 (샘플셋 필요) |
+| `serve` | API 서버 | ⏳ P2 |

pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "luke-scribe"
+version = "0.1.0"
+description = "내부용 로컬 STT 전사 API (faster-whisper, hardware-adaptive)"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "typer>=0.12",
+    "rich>=13.7",
+    "psutil>=5.9",
+    "nvidia-ml-py>=12.535",
+    "huggingface-hub>=0.24",
+]
+
+[project.optional-dependencies]
+# 엔진 — transcribe/bench 증분에서 설치 (uv sync --extra engine)
+engine = ["faster-whisper>=1.0.3", "av>=11"]
+# GPU CUDA 런타임 (faster-whisper GPU 추론 시)
+gpu = ["nvidia-cublas-cu12", "nvidia-cudnn-cu12"]
+# P2 API + Queue
+api = ["fastapi>=0.110", "uvicorn[standard]>=0.29", "redis>=5.0", "rq>=1.16"]
+# P5 옵션
+diarize = ["pyannote.audio>=3.1"]
+llm = ["openai>=1.30"]
+
+[project.scripts]
+luke-scribe = "luke_scribe.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/luke_scribe"]
+
+[dependency-groups]
+dev = ["pytest>=8.2", "ruff>=0.5"]

run.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# 개발/Colab 실행 래퍼 — Docker 없이 순수 Python (계획 §3.10d).
+set -euo pipefail
+cd "$(dirname "$0")"
+exec uv run luke-scribe "$@"

src/luke_scribe/__init__.py

@@ -0,0 +1,3 @@
+"""luke_scribe — 내부용 로컬 STT 전사 API (faster-whisper, hardware-adaptive)."""
+
+__version__ = "0.1.0"

src/luke_scribe/cli.py

@@ -0,0 +1,73 @@
+"""CLI — typer. `detect`(구현) + transcribe/bench/serve(스텁). 스펙 §배포."""
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from .devices import DeviceManager
+
+app = typer.Typer(add_completion=False, help="luke_scribe — 로컬 STT 전사 (hardware-adaptive)")
+console = Console()
+
+
+@app.command()
+def detect(
+    device: str = typer.Option("auto", help="auto|cpu|cuda"),
+    compute_type: str = typer.Option(None, "--compute-type", help="강제 compute_type(float16|int8|int8_float16)"),
+    workers: int = typer.Option(None, help="워커수 오버라이드"),
+) -> None:
+    """하드웨어 감지 → 능력등급(T0~T3)/정밀도/워커수 산정 (AC-2/3, 측정 전 정적 추정)."""
+    profile = DeviceManager.detect(
+        force_device=(None if device == "auto" else device),
+        force_compute_type=compute_type,
+        workers_override=workers,
+    )
+    table = Table(title="luke_scribe · device profile", show_header=False, title_style="bold cyan")
+    table.add_row("device", f"{profile.kind}  ({profile.name})")
+    if profile.compute_capability:
+        table.add_row("compute capability", profile.compute_capability)
+    if profile.vram_total_mb:
+        table.add_row("VRAM (free/total)", f"{profile.vram_free_mb} / {profile.vram_total_mb} MB")
+    table.add_row("RAM", f"{profile.ram_total_mb} MB")
+    table.add_row("disk free", f"{profile.disk_free_mb} MB")
+    table.add_row("compute_type", profile.compute_type)
+    table.add_row("capability tier", f"[bold]{profile.tier.value}[/]")
+    table.add_row("max workers", str(profile.max_workers))
+    for lane, model in profile.served_models.items():
+        table.add_row(f"served · {lane}", model)
+    table.add_row("measured", "yes" if profile.measured else "no (정적 추정)")
+    console.print(table)
+    for note in profile.notes:
+        console.print(f"  • {note}", style="yellow")
+
+
+def _todo(name: str, hint: str = "") -> None:
+    console.print(f"[yellow]'{name}' 은 아직 미구현입니다 (P1 진행 중).[/] {hint}")
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def transcribe(file: str = typer.Argument(..., help="오디오/영상 파일")) -> None:
+    """단발 파일 전사 (다음 증분: engine + ffmpeg ingest)."""
+    _todo("transcribe", "→ `uv sync --extra engine` 후 구현 예정")
+
+
+@app.command()
+def bench(samples: str = typer.Option(None, help="라벨된 KO+EN 샘플 디렉터리")) -> None:
+    """turbo vs large-v3 도메인 벤치 게이트 (샘플셋 확보 후)."""
+    _todo("bench", "→ samples/ 라벨셋 필요")
+
+
+@app.command()
+def serve() -> None:
+    """API 서버 (P2)."""
+    _todo("serve", "→ P2 (FastAPI + Redis/RQ)")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/luke_scribe/config.py

@@ -0,0 +1,38 @@
+"""런타임 설정 — env(`SCRIBE_*`) / `.env` 로 오버라이드. 스펙 §config."""
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="SCRIBE_", env_file=".env", extra="ignore")
+
+    # 모델 (경로별 기본 — 하이브리드; P1 bench 결과에 따라 단일 turbo로 통일 가능)
+    model_realtime: str = "large-v3-turbo"
+    model_batch: str = "large-v3"
+
+    # 디바이스 (auto|cpu|cuda|cuda:0) — Device Manager가 자동 산정, 강제 가능
+    device: str = "auto"
+    compute_type: str | None = None      # None=자동(cc/VRAM 기반)
+    workers: int | None = None           # None=자동 산정
+
+    # 언어 (기본 ko, 요청별 override)
+    language: str = "ko"
+
+    # 입력 절대 상한 (초과 413)
+    max_duration_s: int = 4 * 3600       # 4h
+    max_size_bytes: int = 2 * 1024 * 1024 * 1024  # 2GB
+
+    # 보관/큐/인증 (P2+)
+    retention_days: int = 7
+    redis_url: str | None = None
+    api_keys: list[str] = []
+
+    # 터널 (P5)
+    tunnel: str = "none"                 # none|cloudflare|ngrok
+
+    # 모델 캐시 디렉터리 (None=HF 기본)
+    model_cache_dir: str | None = None
+
+
+settings = Settings()

src/luke_scribe/devices/__init__.py

@@ -0,0 +1,5 @@
+"""Device Manager — GPU/CPU 감지 → 능력등급/정밀도/워커수 산정 (스펙 §6, 계획 §3.6)."""
+from .manager import DeviceManager
+from .profile import CapabilityTier, DeviceProfile
+
+__all__ = ["DeviceManager", "DeviceProfile", "CapabilityTier"]

src/luke_scribe/devices/manager.py

@@ -0,0 +1,125 @@
+"""DeviceManager — 감지 → 정밀도/능력등급/워커수 산정 (계획 §3.6, AC-2/3).
+
+현재는 정적 추정(보수 상수). 후속: 부팅 시 모델 1회 로드 실측(`measured=True`)으로 대체.
+"""
+from __future__ import annotations
+
+import os
+
+from .profile import HEADROOM, MODEL_FOOTPRINT_MB, CapabilityTier, DeviceProfile
+from .vram_probe import GpuInfo, probe_disk_free_mb, probe_gpus, probe_ram_mb
+
+TURBO = "large-v3-turbo"
+V3 = "large-v3"
+
+
+def _select_compute_type(cc: tuple[int, int], free_mb: int) -> str:
+    """정밀도 자동 선택 (계획 §3.6)."""
+    major = cc[0]
+    if major >= 7:  # Volta+ : fp16 효율
+        return "float16" if free_mb >= 12000 else "int8_float16"
+    if major == 6:  # Pascal (예: GTX 1050) — fp16 비효율 → int8
+        return "int8"
+    return "int8"
+
+
+def _fits(model: str, ct: str, free_mb: int) -> bool:
+    fp = MODEL_FOOTPRINT_MB.get((model, ct))
+    return fp is not None and fp * HEADROOM <= free_mb
+
+
+def _both_fit(ct: str, free_mb: int) -> bool:
+    a = MODEL_FOOTPRINT_MB.get((TURBO, ct))
+    b = MODEL_FOOTPRINT_MB.get((V3, ct))
+    return a is not None and b is not None and (a + b) * HEADROOM <= free_mb
+
+
+def _cpu_workers(override: int | None) -> int:
+    return override or max(1, (os.cpu_count() or 2) // 4)
+
+
+def _cpu_profile(
+    *, name: str, ram: int, disk: int, override: int | None,
+    gpu: GpuInfo | None = None, notes: list[str] | None = None,
+) -> DeviceProfile:
+    return DeviceProfile(
+        kind="cpu",
+        name=name,
+        compute_capability=(f"{gpu.compute_capability[0]}.{gpu.compute_capability[1]}" if gpu else None),
+        vram_total_mb=(gpu.vram_total_mb if gpu else 0),
+        vram_free_mb=(gpu.vram_free_mb if gpu else 0),
+        ram_total_mb=ram,
+        disk_free_mb=disk,
+        compute_type="int8",
+        tier=CapabilityTier.T0_CPU,
+        max_workers=_cpu_workers(override),
+        served_models={"realtime": f"{TURBO}@cpu", "batch": f"{TURBO}@cpu"},
+        notes=(notes or []) + ["large-v3 GPU 미제공(CPU 경로)"],
+    )
+
+
+class DeviceManager:
+    @staticmethod
+    def detect(
+        force_device: str | None = None,
+        force_compute_type: str | None = None,
+        workers_override: int | None = None,
+    ) -> DeviceProfile:
+        ram = probe_ram_mb()
+        disk = probe_disk_free_mb(".")
+        gpus = probe_gpus()
+
+        # 강제 CPU 또는 GPU 없음 → T0
+        if force_device == "cpu" or not gpus:
+            note = (
+                "GPU 감지됨이나 --device cpu 강제" if (force_device == "cpu" and gpus)
+                else "GPU 미감지 → CPU"
+            )
+            return _cpu_profile(name="CPU", ram=ram, disk=disk, override=workers_override, notes=[note])
+
+        gpu = gpus[0]
+        cc = gpu.compute_capability
+        ct = force_compute_type or _select_compute_type(cc, gpu.vram_free_mb)
+
+        # turbo조차 GPU에 안 들어가면 → CPU 강등(T0)
+        if not _fits(TURBO, ct, gpu.vram_free_mb):
+            need = int(MODEL_FOOTPRINT_MB[(TURBO, ct)] * HEADROOM)
+            return _cpu_profile(
+                name=f"CPU (GPU={gpu.name} 2GB급 부족)", ram=ram, disk=disk,
+                override=workers_override, gpu=gpu,
+                notes=[f"{gpu.name} free {gpu.vram_free_mb}MB < turbo {need}MB(헤드룸 포함) → CPU 강등(T0)"],
+            )
+
+        # turbo는 GPU OK → large-v3 적재 여부로 등급 분기
+        notes: list[str] = []
+        if not _fits(V3, ct, gpu.vram_free_mb):
+            tier = CapabilityTier.T1_TURBO_GPU
+            served = {"realtime": f"{TURBO}@cuda", "batch": f"{TURBO}@cuda"}
+            notes.append("large-v3 미제공 → 배치도 turbo")
+        elif not _both_fit(ct, gpu.vram_free_mb):
+            tier = CapabilityTier.T2_SWAP
+            served = {"realtime": f"{TURBO}@cuda", "batch": f"{V3}@cuda (swap)"}
+            notes.append("turbo/large-v3 동시상주 불가 → 호출별 load/unload")
+        else:
+            tier = CapabilityTier.T3_CORESIDENT
+            served = {"realtime": f"{TURBO}@cuda", "batch": f"{V3}@cuda"}
+
+        # 워커수 = floor((free - reserve) / per_worker), reserve=상주 모델 헤드룸
+        per_worker = MODEL_FOOTPRINT_MB[(TURBO, ct)]
+        reserve = int(per_worker * (HEADROOM - 1.0))
+        est = max(1, (gpu.vram_free_mb - reserve) // per_worker)
+
+        return DeviceProfile(
+            kind="cuda",
+            name=gpu.name,
+            compute_capability=f"{cc[0]}.{cc[1]}",
+            vram_total_mb=gpu.vram_total_mb,
+            vram_free_mb=gpu.vram_free_mb,
+            ram_total_mb=ram,
+            disk_free_mb=disk,
+            compute_type=ct,
+            tier=tier,
+            max_workers=workers_override or est,
+            served_models=served,
+            notes=notes,
+        )

src/luke_scribe/devices/profile.py

@@ -0,0 +1,46 @@
+"""DeviceProfile 모델 + 능력등급 + 모델 VRAM 보수 상수 (계획 §3.6)."""
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class CapabilityTier(str, Enum):
+    """부팅 실측으로 자동판정 — "제공 가능 모델"을 등급이 결정 (무음 강등 아님)."""
+
+    T0_CPU = "T0_CPU"            # GPU로 turbo도 무리/GPU 없음 → turbo@CPU
+    T1_TURBO_GPU = "T1_TURBO_GPU"  # turbo는 GPU OK, large-v3 무리 (배치도 turbo)
+    T2_SWAP = "T2_SWAP"            # large-v3 OK, turbo와 동시상주 불가 → load/unload
+    T3_CORESIDENT = "T3_CORESIDENT"  # turbo + large-v3 동시 적재 가능
+
+
+# 보수 기본 상수 (MB) — 측정 전 폴백. 계획 §3.6.
+# (부팅 시 실제 로드 측정으로 대체 예정: vram_probe --probe-load)
+MODEL_FOOTPRINT_MB: dict[tuple[str, str], int] = {
+    ("large-v3", "float16"): 10000,
+    ("large-v3", "int8_float16"): 5500,
+    ("large-v3", "int8"): 3500,
+    ("large-v3-turbo", "float16"): 4000,
+    ("large-v3-turbo", "int8_float16"): 2400,
+    ("large-v3-turbo", "int8"): 1800,
+}
+HEADROOM = 1.3  # 적재 헤드룸 배수
+
+
+class DeviceProfile(BaseModel):
+    """감지 결과 + 산정값. /v1/system·detect 가 그대로 노출."""
+
+    kind: str                              # "cuda" | "cpu"
+    name: str
+    compute_capability: str | None = None
+    vram_total_mb: int = 0
+    vram_free_mb: int = 0
+    ram_total_mb: int = 0
+    disk_free_mb: int = 0
+    compute_type: str
+    tier: CapabilityTier
+    max_workers: int = 1
+    served_models: dict[str, str] = Field(default_factory=dict)  # {"realtime":..., "batch":...}
+    measured: bool = False                 # True=모델 실측, False=정적 추정
+    notes: list[str] = Field(default_factory=list)

src/luke_scribe/devices/vram_probe.py

@@ -0,0 +1,72 @@
+"""하드웨어 실측 — GPU(NVML)/RAM/디스크. 의존성 없거나 GPU 없으면 우아하게 빈 결과."""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+
+
+@dataclass
+class GpuInfo:
+    index: int
+    name: str
+    compute_capability: tuple[int, int]
+    vram_total_mb: int
+    vram_free_mb: int
+
+
+def probe_gpus() -> list[GpuInfo]:
+    """NVML로 GPU 목록·VRAM·compute capability 실측. 없으면 []."""
+    try:
+        import pynvml  # nvidia-ml-py
+    except ImportError:
+        return []
+    try:
+        pynvml.nvmlInit()
+    except Exception:
+        return []
+
+    gpus: list[GpuInfo] = []
+    try:
+        for i in range(pynvml.nvmlDeviceGetCount()):
+            h = pynvml.nvmlDeviceGetHandleByIndex(i)
+            name = pynvml.nvmlDeviceGetName(h)
+            if isinstance(name, bytes):
+                name = name.decode()
+            mem = pynvml.nvmlDeviceGetMemoryInfo(h)
+            try:
+                major, minor = pynvml.nvmlDeviceGetCudaComputeCapability(h)
+            except Exception:
+                major, minor = (0, 0)
+            gpus.append(
+                GpuInfo(
+                    index=i,
+                    name=name,
+                    compute_capability=(major, minor),
+                    vram_total_mb=int(mem.total // (1024 * 1024)),
+                    vram_free_mb=int(mem.free // (1024 * 1024)),
+                )
+            )
+    except Exception:
+        return []
+    finally:
+        try:
+            pynvml.nvmlShutdown()
+        except Exception:
+            pass
+    return gpus
+
+
+def probe_ram_mb() -> int:
+    try:
+        import psutil
+
+        return int(psutil.virtual_memory().total // (1024 * 1024))
+    except Exception:
+        return 0
+
+
+def probe_disk_free_mb(path: str = ".") -> int:
+    try:
+        return int(shutil.disk_usage(path).free // (1024 * 1024))
+    except Exception:
+        return 0

tests/test_device_manager.py

@@ -0,0 +1,79 @@
+"""Device Manager 능력등급/정밀도/오버라이드 결정 로직 (계획 §8 unit).
+
+실하드웨어는 T0만 밟으므로 T1~T3은 합성 VRAM 값으로 검증.
+"""
+from __future__ import annotations
+
+from luke_scribe.devices import manager as m
+from luke_scribe.devices.manager import DeviceManager
+from luke_scribe.devices.profile import CapabilityTier
+from luke_scribe.devices.vram_probe import GpuInfo
+
+
+def _patch(monkeypatch, gpus: list[GpuInfo]) -> None:
+    monkeypatch.setattr(m, "probe_gpus", lambda: gpus)
+    monkeypatch.setattr(m, "probe_ram_mb", lambda: 16000)
+    monkeypatch.setattr(m, "probe_disk_free_mb", lambda path=".": 100000)
+
+
+def _gpu(cc: tuple[int, int], free: int, name: str = "TestGPU") -> GpuInfo:
+    return GpuInfo(0, name, cc, free + 100, free)
+
+
+def test_no_gpu_is_t0_cpu(monkeypatch):
+    _patch(monkeypatch, [])
+    p = DeviceManager.detect()
+    assert p.kind == "cpu"
+    assert p.tier == CapabilityTier.T0_CPU
+    assert p.compute_type == "int8"
+
+
+def test_weak_pascal_downgrades_to_cpu(monkeypatch):
+    # GTX 1050: cc6.1, free 1990 → turbo(int8, 2340MB 헤드룸) 부족 → CPU 강등
+    _patch(monkeypatch, [_gpu((6, 1), 1990, "GTX 1050")])
+    p = DeviceManager.detect()
+    assert p.tier == CapabilityTier.T0_CPU
+    assert p.kind == "cpu"
+    assert p.vram_free_mb == 1990  # GPU 정보는 보존(투명성)
+    assert any("강등" in n for n in p.notes)
+
+
+def test_t1_turbo_only(monkeypatch):
+    # cc7.5, free 6000 → int8_float16; turbo 적재 OK, large-v3 무리
+    _patch(monkeypatch, [_gpu((7, 5), 6000)])
+    p = DeviceManager.detect()
+    assert p.tier == CapabilityTier.T1_TURBO_GPU
+    assert p.compute_type == "int8_float16"
+    assert p.served_models["batch"].startswith("large-v3-turbo")
+
+
+def test_t2_swap(monkeypatch):
+    # cc7.5, free 16000 → float16; turbo·large-v3 각각 OK, 동시상주는 불가
+    _patch(monkeypatch, [_gpu((7, 5), 16000)])
+    p = DeviceManager.detect()
+    assert p.tier == CapabilityTier.T2_SWAP
+    assert p.compute_type == "float16"
+    assert "swap" in p.served_models["batch"]
+
+
+def test_t3_coresident(monkeypatch):
+    # A100급: cc8.0, free 40000 → float16; turbo+large-v3 동시상주
+    _patch(monkeypatch, [_gpu((8, 0), 40000, "A100")])
+    p = DeviceManager.detect()
+    assert p.tier == CapabilityTier.T3_CORESIDENT
+    assert p.compute_type == "float16"
+    assert p.served_models["batch"] == "large-v3@cuda"
+    assert p.max_workers >= 1
+
+
+def test_force_cpu_override(monkeypatch):
+    _patch(monkeypatch, [_gpu((8, 0), 40000)])
+    p = DeviceManager.detect(force_device="cpu")
+    assert p.tier == CapabilityTier.T0_CPU
+    assert p.kind == "cpu"
+
+
+def test_workers_override(monkeypatch):
+    _patch(monkeypatch, [_gpu((8, 0), 40000)])
+    p = DeviceManager.detect(workers_override=3)
+    assert p.max_workers == 3