lecture-notes

English README

lecture-notes는 강의 전사 *.txt 파일을 재귀적으로 찾아 4단계 AI 워크플로우로 처리한 뒤, 원본 파일 옆에 정리된 Markdown 노트를 생성하는 Python CLI입니다.

다음과 같은 용도에 맞춰져 있습니다.

• 전사 오류 교정
• 읽기 쉬운 문단 구조로 정리
• 복습용 핵심 요약 생성
• 코넬 노트테이킹법 기반 상세 필기본 생성
• Obsidian 친화적인 Markdown 출력

내부적으로 OpenAI Python SDK를 사용합니다. OpenAI 공식 API는 기본적으로 Responses API를 사용하고, OpenAI 호환 서버는 Chat Completions API를 사용합니다.

설치

GitHub에서 바로 설치:

uv tool install git+https://github.com/3ae3ae/lecture-notes.git

기존 설치 갱신:

uv tool install --refresh git+https://github.com/3ae3ae/lecture-notes.git

로컬 개발 환경에서 설치:

uv tool install .

빠른 시작

처음 실행하면 전역 설정파일이 없을 때 자동으로 생성합니다. 기본 설정은 OPENAI_API_KEY 환경변수를 참조합니다.

lecture-notes ./lectures --dry-run
export OPENAI_API_KEY="your-api-key"

현재 디렉터리 기준으로 실행:

lecture-notes

특정 폴더를 지정해 실행:

lecture-notes ./lectures

API 호출 없이 처리 대상만 확인:

lecture-notes ./lectures --dry-run

단계별 진행 로그까지 보기:

lecture-notes ./lectures --verbose

OpenAI 호환 서버 사용

OpenAI 호환 제공자를 사용할 때는 base URL과 모델명을 함께 설정하면 됩니다.

[providers.local]
type = "compatible"
base_url = "https://your-openai-compatible-server/v1"
api_key_env = "LECTURE_NOTES_API_KEY"

[stages.correction]
provider = "local"
model = "your-model-name"

그 다음 api_key_env가 참조하는 환경변수에 API 키를 넣고 실행합니다.

export LECTURE_NOTES_API_KEY="your-api-key"
lecture-notes ./lectures

설정파일 사용

복수 모델이나 복수 API URL을 함께 쓰려면 lecture-notes.toml을 사용합니다. 설정파일 탐색 순서는 다음과 같습니다.

1. --config로 지정한 파일
2. 현재 작업 디렉터리의 lecture-notes.toml
3. 사용자 전역 설정 ~/.config/lecture-notes/config.toml

로컬/전역 설정이 모두 없으면 첫 실행 시 전역 기본 설정파일을 자동 생성합니다. 그래서 uv tool install로 설치한 뒤에도 별도 복사 없이 바로 사용할 수 있습니다.

확인:

lecture-notes --print-config-paths

[providers.openai]
type = "openai"
api_key_env = "OPENAI_API_KEY"

[providers.local]
type = "compatible"
base_url = "http://localhost:1234/v1"
api_key_env = "LECTURE_NOTES_API_KEY"

[stages.correction]
provider = "local"
model = "qwen-transcriber"

[stages.formatting]
provider = "local"
model = "qwen-transcriber"

[stages.summary]
provider = "openai"
model = "gpt-5.4-mini"
max_output_tokens = 2000

[stages.summary.request.reasoning]
effort = "minimal"

[stages.cornell]
provider = "openai"
model = "gpt-5.4"

[stages.cornell.request.reasoning]
effort = "medium"

Provider type은 다음 값을 지원합니다.

• openai: OpenAI 공식 API. 기본적으로 Responses API를 사용합니다.
• compatible: OpenAI 호환 Chat Completions 서버. OpenAI 전용 요청 인자를 사용하면 API 호출 전에 오류로 중단합니다.
• local: compatible의 별칭입니다.

필요하면 provider에 api = "responses" 또는 api = "chat_completions"를 명시할 수 있습니다. 단, responses는 type = "openai" provider에서만 사용할 수 있습니다. OpenAI Responses API를 사용할 때는 기본적으로 store = false가 적용됩니다.

provider나 stage에는 [...request] 하위 테이블을 둘 수 있습니다. 이 값은 OpenAI Python SDK의 responses.create(..., **request) 또는 chat.completions.create(..., **request)로 전달됩니다. provider의 request는 기본값처럼 쓰이고, stage의 request가 같은 키를 덮어씁니다.

[providers.openai.request.metadata]
app = "lecture-notes"

[stages.summary]
provider = "openai"
model = "gpt-5.4"
max_output_tokens = 8000
service_tier = "flex"

[stages.summary.request.reasoning]
effort = "medium"

공통 요청 인자:

• temperature
• top_p
• max_tokens
• max_completion_tokens
• max_output_tokens
• presence_penalty
• frequency_penalty
• seed
• timeout

temperature처럼 모델별로 지원 여부가 다른 인자는 사용하는 모델이나 호환 서버가 지원할 때만 설정합니다.

OpenAI Responses provider에서 자주 쓰는 옵션 예시:

[stages.summary]
provider = "openai"
model = "gpt-5.4"
max_output_tokens = 8000
service_tier = "flex"
store = false

[stages.summary.request.reasoning]
effort = "medium"

OpenAI 호환 Chat Completions provider에서 자주 쓰는 옵션 예시:

[stages.cornell]
provider = "local"
model = "your-model-name"
max_completion_tokens = 12000
temperature = 0.2
top_p = 0.9
presence_penalty = 0.1
frequency_penalty = 0.1
seed = 42
timeout = 120

토큰 제한 인자 규칙:

• Chat Completions는 max_tokens 또는 max_completion_tokens를 사용합니다.
• Responses는 max_output_tokens를 사용합니다.
• Responses provider에서 max_tokens나 max_completion_tokens를 쓰면 오류로 중단합니다.
• 같은 stage/provider에서 max_tokens, max_completion_tokens, max_output_tokens를 섞어 쓰면 오류로 중단합니다.

OpenAI 전용 요청 인자:

• reasoning
• service_tier
• prompt_cache_key
• prompt_cache_retention
• store
• metadata
• safety_identifier

Profile이 필요하면 [profiles.<name>.stages] 아래에 단계 설정을 둘 수 있습니다.

[profiles.fast.stages.summary]
provider = "openai"
model = "gpt-5.4-mini"

[profiles.fast.stages.summary.request.reasoning]
effort = "minimal"

실행:

lecture-notes ./lectures --profile fast
lecture-notes ./lectures --config ./my-lecture-notes.toml

CLI 옵션

• lecture-notes [PATH]
• --config <path>
• --print-config-paths
• --profile <name>
• --model <name>
• --api-key <key>
• --base-url <url>
• --include-glob <pattern> 반복 가능
• --exclude-dir <name> 반복 가능
• --dry-run
• --verbose
• --fail-fast
• --overwrite
• --limit <n>
• --jobs <n>
• --retries <n>
• --retry-backoff <seconds>

--model, --api-key, --base-url은 세 옵션을 모두 함께 제공할 때만 전체 stage를 임시 OpenAI 호환 provider로 실행합니다. 일부만 제공하면 오류로 중단합니다.

동작 방식

대상 디렉터리 아래의 각 *.txt 파일에 대해 다음 순서로 처리합니다.

1. 전사 오류를 교정하되 의미를 최대한 보존합니다.
2. 전사문을 읽기 쉬운 문단 구조로 재정리합니다.
3. 복습에 유용한 핵심 요약을 생성합니다.
4. 전체 전사문을 대체해 복습할 수 있는 코넬 노트 형식의 필기본을 생성합니다.

그 다음 같은 basename의 Markdown 파일을 원본 옆에 저장합니다.

• lecture.txt -> lecture.md
• lecture.md가 이미 있으면 해당 txt는 건너뜁니다.

기본 제외 디렉터리:

• .git
• .venv
• node_modules
• __pycache__

텍스트 디코딩 fallback 순서:

• utf-8
• utf-8-sig
• cp949

추가 동작:

• 한글 파일명과 공백이 포함된 파일명을 지원합니다.
• --verbose 없이도 파일 단위 진행 상황을 출력합니다.
• --verbose를 주면 파이프라인 단계별 로그를 추가로 출력합니다.
• 출력 파일은 임시 파일에 먼저 쓴 뒤 원자적으로 교체합니다.
• --jobs를 주면 여러 파일을 병렬 처리하되, 한 파일 내부의 4단계 순서는 유지합니다.
• 일시적인 timeout, rate limit, 5xx 오류는 --retries와 --retry-backoff 설정에 따라 재시도합니다.

출력 형식

생성되는 Markdown은 Obsidian에서 보기 좋도록 대괄호 라벨 대신 헤딩을 사용합니다.

## 요약

### 핵심 요약
- ...

### 교수님 강조 포인트
- ...

## 코넬 노트

### 단서 / 질문
- ...

### 필기
- ...

### 요약
- ...

## 전체 전사문

...

환경 변수

환경변수는 자동 fallback 설정으로 쓰지 않습니다. 설정파일의 provider가 api_key_env = "OPENAI_API_KEY"처럼 명시적으로 참조한 경우에만 해당 환경변수를 읽습니다.

예:

[providers.openai]
type = "openai"
api_key_env = "OPENAI_API_KEY"

export OPENAI_API_KEY="your-api-key"

전체 설정파일 탐색 순서는 --config, 현재 작업 디렉터리의 lecture-notes.toml, 전역 설정 순서입니다.

uv tool로 설치한 경우에도 전역 설정은 ~/.config/lecture-notes/config.toml에 저장됩니다. 폴더별 설정을 쓰고 싶으면 해당 폴더에 lecture-notes.toml을 두면 전역 설정보다 우선 적용됩니다.

개발

테스트 실행:

python -m unittest discover -s tests

라이선스

MIT. 자세한 내용은 LICENSE를 참고하세요.