Nutti — AI 광고/콘텐츠 자동화 파이프라인

Purpose

애견 수제간식 쇼핑몰을 위한 대본 생성 → AI 영상 제작 → 업로드 → 성과 분석 자동화 파이프라인. 5단계 흐름 사이에 텔레그램/디스코드 기반 사람-검수 게이트가 있다. N8n 스케줄러가 nutti run(또는 파이썬 함수)을 호출하고, 실제 로직·검수·업로드는 이 패키지가 담당한다. (기획서: Notion "🐾 Nutti | AI 광고 자동화 계획서")

전체 플로우

대본 생성(Claude) → [팩트체크] → [검수① 텔레그램]
  → 영상 제작(Hedra+Seedance+자막) → [검수② 텔레그램]
  → 메타데이터(제목·태그) → [검수③ 디스코드]
  → 업로드(YouTube/Instagram) → 성과 수집·분석(Claude) → 다음 대본 개선(피드백 루프)

Key Files

File	Description
`pyproject.toml`	패키지/의존성/스크립트(`nutti`)·ruff·pytest 설정
`requirements.txt`	런타임 의존성 평면 목록
`.env.example`	모든 외부 서비스 키·설정 템플릿 (실제 `.env`는 gitignore)
`README.md`	사람용 개요·시작 가이드
`demo_local.py`	(선택) dry-run 로컬 시연 스크립트

Subdirectories

Directory	Purpose
`nutti/`	애플리케이션 패키지 (see `nutti/AGENTS.md`)
`tests/`	pytest 테스트 (see `tests/AGENTS.md`)
`.github/workflows/`	GitHub Actions CI (ruff + pytest)

For AI Agents

핵심 계약 — DRY-RUN 우선

NUTTI_DRY_RUN=true(기본값)이면 외부 API 키 없이 전 파이프라인이 결정적 시뮬레이션으로 동작한다. 모든 외부 연동(nutti/integrations, nutti/review, nutti/storage)은 dry_run 분기에서 네트워크/SDK 없이 더미 결과를 반환해야 한다. 실제 연동을 추가할 때도 이 계약을 깨지 말 것.

개발 워크플로 · 모델 라우팅

브랜칭·커밋 전 검증·CI·PR·머지 정책·적대적 리뷰 루프·모델 라우팅은 루트 CLAUDE.md가 단일 출처 — 그것을 따른다.

Testing Requirements

모든 단위 테스트는 dry_run 또는 fake 주입으로 네트워크 없이 돌아야 한다.
새 코드 경로(특히 라이브 분기)는 fake 클라이언트 주입으로 테스트한다.

Common Patterns

도메인 모델은 Pydantic v2(nutti/models.py)에 정의, 플랫폼별 응답을 공통 모델로 정규화.
주석·docstring은 한국어 사용(기존 스타일 유지). ruff line-length=100.
외부 클라이언트는 settings와 주입 가능한 의존성(http/client/store/clock/sleep)을 받아 테스트 가능하게.

Dependencies

External

anthropic — Claude(대본·메타데이터·팩트체크·분석)
pydantic / pydantic-settings — 모델·환경설정
httpx — HTTP 클라이언트 / structlog — 로깅 / typer — CLI

FilesExpand file tree

AGENTS.md

Latest commit

History