Report Maker

다양한 소스(URL, PDF, Markdown)를 분석하여 사용자 맞춤형 보고서를 생성하는 로컬 웹 애플리케이션.

Google Gemini API를 활용하여 도메인 분석, 전문가 페르소나 기반 작성, 이미지 생성(Imagen)을 수행하고, PDF와 Markdown으로 내보냅니다.

주요 기능

• 다중 소스 입력: URL 크롤링, PDF 파싱, Markdown 파일 업로드
• AI 보고서 생성 파이프라인: 도메인 분석 → 전문가 페르소나 → 구조 설계 → 섹션별 작성 → 분량 조정
• 딥리서치 모드: Google Search grounding을 통한 웹 검색 보강 (선택)
• 이미지 생성: Gemini Imagen으로 인포그래픽, 다이어그램 자동 생성
• 실시간 진행률: SSE(Server-Sent Events) 기반 진행 상황 추적
• PDF 내보내기: 표지 + 본문 + 표 + 이미지가 포함된 전문 보고서
• Markdown 미리보기: 생성된 보고서를 브라우저에서 렌더링하여 확인

기술 스택

구분	기술
Backend	Python, FastAPI, SQLite (aiosqlite)
Frontend	React, TypeScript, Vite, Tailwind CSS
AI	Google Gemini API (gemini-2.5-flash), Imagen (gemini-3.1-flash-image-preview)
PDF	WeasyPrint
Markdown	react-markdown, remark-gfm

사전 요구사항

• Python 3.11+
• Node.js 18+
• Google API Key (Gemini API 활성화 필요)
• Homebrew (macOS — WeasyPrint 시스템 의존성)

설치

1. 저장소 클론

git clone https://github.com/namojo/report-maker.git
cd report-maker

2. 시스템 의존성 설치 (macOS)

WeasyPrint가 Pango, GLib 등의 시스템 라이브러리를 필요로 합니다.

brew install pango gdk-pixbuf libffi

3. API 키 설정

프로젝트 루트에 .env.local 파일을 생성합니다.

echo 'GOOGLE_API_KEY=여기에_API_키_입력' > .env.local

4. 실행

./start.sh

이 스크립트가 자동으로:

• Python 가상환경 생성 및 의존성 설치
• Node.js 의존성 설치
• 백엔드 서버 (port 8000) 시작
• 프론트엔드 개발 서버 (port 5173) 시작

수동 설치 (start.sh 대신)

# Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

# 실행 (터미널 2개)
# 터미널 1: Backend
cd backend && source .venv/bin/activate
DYLD_LIBRARY_PATH=/opt/homebrew/lib python -m uvicorn main:app --port 8000 --reload

# 터미널 2: Frontend
cd frontend && npm run dev

사용법

1. 소스 추가

http://localhost:5173에 접속하여 "새 보고서 만들기"를 클릭합니다.

• URL 추가: 분석할 웹 페이지 URL을 입력
• 파일 업로드: PDF 또는 Markdown 파일을 드래그 앤 드롭

2. 보고서 설정

• 주제: 보고서의 주제를 입력
• 페이지 수: 1~500페이지 (방향키 또는 직접 입력)
• 문체: 엔지니어링 / 경영진용 / 학술용 / 커스텀
• 딥리서치: ON 시 웹 검색으로 추가 자료를 자동 수집
• 출력 포맷: PDF, Markdown

3. 생성 및 다운로드

"보고서 생성" 클릭 후 실시간 진행률을 확인합니다. 완료 후 PDF/Markdown 다운로드 및 미리보기가 가능합니다.

프로젝트 구조

report-maker/
├── start.sh                  # 원클릭 실행 스크립트
├── .env.local                # API 키 (gitignore)
├── backend/
│   ├── main.py               # FastAPI 앱
│   ├── config.py             # 설정 (.env.local 로드)
│   ├── models.py             # Pydantic 모델
│   ├── database.py           # SQLite CRUD
│   ├── routers/
│   │   ├── sources.py        # 소스 관리 API
│   │   ├── reports.py        # 보고서 생성/조회 API
│   │   └── exports.py        # 다운로드/미리보기/이미지 서빙
│   └── services/
│       ├── ingestion.py      # URL/PDF/MD 파싱
│       ├── report_generator.py  # Gemini 파이프라인
│       └── pdf_exporter.py   # Markdown → PDF
├── frontend/
│   ├── src/
│   │   ├── pages/            # Dashboard, NewReport, ReportDetail
│   │   ├── components/       # UI 컴포넌트
│   │   ├── api.ts            # API 클라이언트
│   │   └── types.ts          # TypeScript 타입
│   └── package.json
└── .claude/                  # 에이전트 팀 하네스 (선택)
    ├── agents/               # 에이전트 정의 4개
    └── skills/               # 오케스트레이터 스킬

API 엔드포인트

Method	Path	설명
POST	/api/sources/upload	파일 업로드 (PDF/MD)
POST	/api/sources/url	URL 소스 추가
GET	/api/sources	소스 목록
DELETE	/api/sources/{id}	소스 삭제
POST	/api/reports	보고서 생성
GET	/api/reports	보고서 목록
GET	/api/reports/{id}	보고서 상세
GET	/api/reports/{id}/progress	SSE 진행률
POST	/api/reports/{id}/retry	실패 보고서 재시도
DELETE	/api/reports/{id}	보고서 삭제
GET	/api/reports/{id}/download/{format}	PDF/MD 다운로드
GET	/api/reports/{id}/preview	Markdown 미리보기
GET	/api/reports/{id}/images/{file}	생성 이미지 서빙

라이선스

MIT