튜토리얼 0: 설치 및 개발 환경 설정

이 가이드에서는 eulerweave를 설치하고 개발 환경을 구성하는 방법을 안내합니다.

사전 요구 사항

요구 사항	최소 버전	비고
Python	3.11+	3.12 권장
pip	23.0+	최신 Python에 기본 포함
git	2.x	저장소 클론용

python --version
# Python 3.12.x   (3.11 이상 필요)

1. 저장소 클론

git clone https://github.com/baida21/eulerweave.git
cd eulerweave

2. 가상 환경 생성

python -m venv .venv
source .venv/bin/activate    # Linux / macOS
# .venv\Scripts\activate     # Windows

3. 설치

개발 시에는 모든 선택적 의존성을 포함한 설치를 권장합니다:

pip install -e ".[dev]"

이 명령으로 설치되는 항목:

핵심 의존성 — typer[all], pydantic, pyyaml, rich
[dev] extras — pytest, pytest-cov, jsonschema 및 모든 선택적 그룹

선택적 의존성 그룹

기능의 일부만 필요한 경우 개별 그룹을 설치할 수 있습니다:

그룹	설치되는 패키지	필요한 경우
`llm`	`httpx>=0.25`	Ollama를 통한 LLM 기반 QnA 생성 (`build_sft_qna`, `build_langextract_qna`)
`parquet`	`pyarrow>=14.0`	Parquet/MDS 내보내기 (`export_parquet`, `export_mds`)
`dedup`	`datasketch>=1.6`	MinHash 기반 중복 제거 (`dedup_minhash`)
`pdf`	`pdfminer.six>=20221105`	PDF 텍스트 추출 (`type: pdf` 입력)
`pdf_ocr`	`pdfminer.six` + `ocrmypdf>=16.0`	PDF OCR 추출 (`strategy: ocr`)
`all`	위의 모든 패키지 (pdf_ocr 제외)	테스트 도구를 제외한 전체 기능
`dev`	`all` + `pytest` + `pytest-cov` + `jsonschema`	전체 개발 환경

예시:

# 핵심 + PDF 지원만
pip install -e ".[pdf]"

# 핵심 + PDF OCR까지
pip install -e ".[pdf_ocr]"

# 핵심 + LLM + PDF (QnA 생성 포함 PDF 파이프라인)
pip install -e ".[llm,pdf]"

# 전체 (dev와 동일하되 테스트 의존성 제외)
pip install -e ".[all]"

4. 설치 확인

eulerweave --help

예상 출력:

 Usage: eulerweave [OPTIONS] COMMAND [ARGS]...

 Eulerflow: Manifest-centric data pipeline for LLM training.

Options:
  --help  Show this message and exit.

Commands:
  new        Scaffold a new manifest YAML.
  validate   Validate a manifest YAML.
  plan       Show execution plan and cost estimate.
  run        Execute a manifest pipeline.
  export     Export data to streaming formats.
  plugins    List installed extractor plugins.
  dataset    Dataset-related commands.

설치된 추출기 플러그인을 확인합니다:

eulerweave plugins list

Extractors:
  txt      eulerweave.core.io.local_files:TxtExtractor          [.txt]
  jsonl    eulerweave.core.io.jsonl:JsonlExtractor               [.jsonl]
  csv      eulerweave.core.io.csv_extractor:CsvExtractor         [.csv]
  parquet  eulerweave.core.io.parquet_extractor:ParquetExtractor [.parquet]
  html     eulerweave.core.io.html_extractor:HtmlExtractor       [.html]
  pdf      eulerweave.core.io.pdf_extractor:PdfExtractor         [.pdf]

6 extractor(s) installed.

5. 테스트 실행

pytest tests/ -q

모든 테스트가 통과해야 합니다. 네트워크/Ollama 관련 테스트는 환경 변수가 없으면 자동으로 skip됩니다.

커버리지를 확인하려면:

pytest tests/ -v --cov=eulerweave --cov-report=term-missing

6. 프로젝트 구조

eulerweave/
  eulerweave/
    cli/                    # CLI 명령어 (new, validate, plan, run, plugins 등)
    core/
      io/                   # 추출기 (jsonl, csv, parquet, html, pdf, txt)
      record.py             # CanonicalRecord Pydantic 모델
      stores/               # 저장소 백엔드
    blocks_builtin/         # 내장 블록 17개
    engine/                 # 컴파일러, 플래너, 로컬 실행기
    registry/               # 플러그인 발견, 블록 카탈로그
    spec/                   # 매니페스트, 타입, 블록 스펙, 메트릭 스키마
    providers/              # LLM 프로바이더 (Ollama 등)
  tests/
    unit/                   # 단위 테스트
    cli/                    # CLI 테스트
    integration/            # 통합 테스트
    fixtures/               # YAML 테스트 데이터
  docs/
    tutorials/              # 이 튜토리얼 시리즈
    architecture/           # 아키텍처 문서
    fixtures/               # 픽스처 인덱스
  pyproject.toml            # 빌드 설정, 의존성, 진입점

내장 블록 (17개)

슬롯	블록	설명
normalize	`normalize_text`	공백 정리, 인코딩 정규화
filter	`heuristic_filter`	길이/품질 기반 필터링
dedup	`dedup_minhash`	MinHash 유사 중복 제거
dedup	`dedup_exact`	SHA-256 정확 중복 제거
metrics	`metrics_text_basic`	텍스트 길이 분포 통계
metrics	`metrics_quality_heuristic`	URL/반복/문자 비율
metrics	`metrics_dedup_report`	중복 제거 리포트
metrics	`metrics_task_format_validate`	SFT 메시지 포맷 검증
metrics	`metrics_text_distribution`	텍스트 분포 분석
metrics	`metrics_language_heuristic`	언어 비율 분석
build_task	`build_sft_messages`	기존 필드 → SFT 형식 매핑
build_task	`build_sft_qna`	LLM 기반 QnA 생성 (Ollama)
build_task	`build_langextract_qna`	LangExtract 방식 QnA 생성
export	`export_jsonl`	JSONL 내보내기
export	`export_parquet`	Parquet 내보내기
export	`export_mds`	MDS 스트리밍 내보내기

내장 추출기 (6개)

이름	지원 형식	옵션
`txt`	`.txt`	—
`jsonl`	`.jsonl`	—
`csv`	`.csv`	`text_column`, `delimiter`
`parquet`	`.parquet`	`text_column`
`html`	`.html`	—
`pdf`	`.pdf`	`strategy` (auto/text/ocr), `page_range`

트러블슈팅

`eulerweave: command not found`

source .venv/bin/activate
pip install -e ".[dev]"

`ModuleNotFoundError: No module named 'pdfminer'`

PDF 지원 의존성을 설치합니다:

pip install -e ".[pdf]"

`ImportError: ocrmypdf` (OCR 사용 시)

OCR 의존성을 설치합니다:

pip install -e ".[pdf_ocr]"

`pyarrow` 임포트 오류

pip install -e ".[parquet]"

다음 단계

튜토리얼 1: 빠른 시작 — 첫 매니페스트 생성부터 JSONL 출력까지
튜토리얼 2: PDF → 훈련 데이터 — 로컬 PDF 문서를 SFT 훈련 데이터로 변환