PrintGuard-AI

인쇄소에 PDF를 넘기기 전에 스스로 검수해 보는 웹앱입니다. 폰트가 빠졌는지, 도련이 모자라지 않는지, 이미지 해상도가 버티는지, 고른 종이에 찍으면 색이 얼마나 달라지는지를 미리 보여 줍니다.

• 공개 사이트: https://print-guard-ai.vercel.app
• 검사 방식이 두 가지입니다. 바로 검사는 서버 없이 브라우저 안에서 끝나고(파일이 어디로도 나가지 않습니다), 에이전트 검사는 에이전트 9개가 같은 계산을 나눠 맡아 누가 무엇을 언제 했는지까지 보여 줍니다.

무엇을 하나

• PDF 검수 — 판형·도련·폰트 포함·이미지 해상도·색 공간·안전 여백·문구(반복 단어, 율/률, 같은 항목 다른 숫자)를 검사하고 페이지 위에 문제 위치를 표시합니다.
• 인쇄 색 차이 예측 — PDF 안 RGB 이미지를 종이별 CMYK ICC 프로파일로 변환해 ΔE2000과 총 잉크량을 계산하고 색 차이 지도를 그립니다(lcms-wasm). 종이 흰색을 측정한 Lab 값을 넣으면 프로파일이 가정한 종이 대신 그 종이 기준으로 옮겨 다시 잽니다(브랜드 종이 근사 보정).
• 종이 489종 — 한국제지연합회 분류 기반 기본 종류 35종에 두성종이·삼원페이퍼 카탈로그와 국내 제지사 공식 제품 페이지에서 모은 브랜드 454종을 더했습니다. 종이 등급별 공개 프로파일 12개를 함께 씁니다.
• 인쇄 불량 점검 — 뒷묻음·눌림·색판 어긋남·농도 얼룩·줄무늬에 대해, 원문으로 확인한 불량 원인이 이 파일·이 종이에 해당하는지만 보여 줍니다(학습 모델이 아닙니다). 위험 점수나 등급은 매기지 않습니다 — 실제 불량 데이터로 세기를 재 본 적이 없기 때문입니다.
• 인쇄 가이드 검색(RAG) — multilingual-e5-small(int8 ONNX)과 2-gram BM25를 섞어 씁니다. 브라우저와 에이전트가 같은 모델 파일을 돌립니다(브라우저는 transformers.js, 서버는 onnxruntime).
• 인쇄소 지도 — 행정안전부 전국 인쇄사 인허가 데이터(영업/정상 17,082곳)와 파주출판도시 입주기업을 지도에 올리고 구글 지도로 이어 줍니다.

검사 방식 두 가지

	바로 검사	에이전트 검사(A2A)
계산하는 곳	이 브라우저 안	에이전트 9개(기본 127.0.0.1:8700~8708)
PDF	어디로도 보내지 않음	에이전트에 올라감
가이드 검색	브라우저가 모델을 받아 직접	guide 에이전트가 대신
볼 수 있는 것	검수 결과	결과 + 누가 언제 무엇을 했는지(의뢰 추적·소통 기록·안전 관문 결정)
필요한 것	없음	에이전트를 켜 둬야 함

에이전트를 켜지 않아도 앱은 바로 검사 모드로 전부 동작합니다. 주소 없이 열면(/) 에이전트 검사가 기본이고, /?mode=direct가 바로 검사입니다.

로그인은 선택입니다. 하지 않아도 검수는 전부 되고, 그때 기록은 그 브라우저에만 남습니다. 헤더 오른쪽에서 구글로 로그인하면 그때까지 한 검수가 계정으로 옮겨 가고, 다른 기기에서도 이어서 보입니다.

에이전트 9개

에이전트	포트	하는 일	런타임
총괄 orchestrator	8700	의뢰를 받아 나눠 보내고 결과를 모읍니다. 바깥에 열리는 창구는 여기 하나뿐입니다	Python
안전 관문 safety	8701	행동 등급(읽기/A/B/C)을 보고 허가합니다. 막히면 막힌 채로 둡니다(fail-closed)	Python
사전 검사 preflight	8702	PDF 구조 검사	Node
색 color	8703	인쇄 색 차이 예측	Node
인쇄 가이드 guide	8704	가이드 원문 검색	Python
종이·위험도 paper	8705	종이 추천, 불량 위험 점검	Node
교정 proofread	8706	오탈자 수정 제안	Python
보고서 report	8708	검수 보고서 작성	Python
원본 수정 designcraft	8709	편집 파일(IDML)을 열어 교정을 반영하고, 새 문서도 만듭니다	Python + DesignCraft MCP

구조

frontend/   Next.js 16 앱 (app/ 화면, lib/ 계산, agents/ Node 에이전트, scripts/ 검증, public/ 데이터)
agents/     에이전트 9종(A2A)과 MCP 서버 — 에이전트 검사 모드의 뒷단
eval/       평가·데이터 생성(Python): 검색 모델 비교, 색 엔진 대조, 종이·인쇄소 수집
deploy/     배포용(에이전트 컨테이너, ICC 내려받기 스크립트)
samples/    시험용 PDF

설치

# 파이썬과 Node를 한 환경에 둡니다(Node 에이전트도 이 node로 돕니다)
conda create -y -n dev python=3.12 nodejs=22
conda activate dev
pip install -r agents/requirements.txt

cd frontend && npm install          # tsx 포함(Node 에이전트 실행용)

그다음 저장소에 없는 파일(모델·wasm·ICC 프로파일)을 채웁니다. 아래 같은 이름의 절을 보세요.

실행

설치는 끝났고 꺼진 것을 되살리기만 하면 되는 상황이라면 RUN.md로 가세요 — 켜는 명령과 증상별(502·530) 판별표만 모아 둔 짧은 문서입니다.

먼저 conda activate dev를 합니다. run_agents.py는 자기를 실행한 파이썬으로 자식 에이전트를 띄우는데, 의존성은 그 환경에만 있습니다. 환경을 켜지 않고 python을 치면 패키지가 없는 시스템 파이썬이 잡힙니다. 그때는 런처가 아무것도 띄우지 않고 멈추면서 어느 파이썬이 잡혔는지 적습니다.

[멈춤] 이 파이썬에는 에이전트 의존성이 없습니다: C:\Users\...\Python312\python.exe

이미 떠 있는 에이전트가 있으면 그것도 켜기 전에 알려 주고 건드리지 않습니다([이미 떠 있음] color (8703)). 겹쳐 띄우면 EADDRINUSE로 죽는데, 화면에서는 먼저 띄운 쪽이 멀쩡히 답하고 있어서 왜 죽었는지가 안 보입니다.

conda activate dev                   # 빼먹으면 에이전트가 안 뜹니다

# 1) 바로 검사만 — 에이전트 없이 브라우저 안에서 전부 계산합니다
cd frontend && npm run dev -- -H 127.0.0.1 -p 8752

# 2) 에이전트 검사까지 — 에이전트 9개를 켜고 앱에서 '에이전트 검사'를 고릅니다
python agents/run_agents.py          # 로그는 agents/.data/logs/<이름>.log
cd frontend && npm run dev -- -H 127.0.0.1 -p 8752

conda activate가 안 먹는 터미널에서는 경로를 직접 줘도 됩니다.

"$HOME/miniforge3/envs/dev/python.exe" agents/run_agents.py   # Windows

매번 적기 번거로우면 agents/.env에 **PG_PYTHON**으로 그 경로를 한 번 적어 두면 됩니다. 그러면 어느 파이썬으로 런처를 불러도 자식 에이전트는 그 파이썬으로 뜹니다.

python agents/run_agents.py guide color처럼 이름을 적으면 일부만 켭니다. 끄는 것은 Ctrl+C 한 번이면 전부 내려갑니다.

공개 사이트에 내 에이전트를 붙여 쓸 때

공개 배포 구성으로 쓰는 경우, 에이전트와 터널은 한 쌍입니다. 둘 중 하나만 켜면 공개 사이트에서 에이전트가 안 보입니다. 둘은 각자 창을 붙잡고 있어서 한 창에서 같이 켤 수 없으므로 터미널 두 개에 각각 띄웁니다.

켜는 폴더가 둘이 다릅니다.

	폴더	왜
에이전트	저장소 루트 — 이 README가 있는 폴더	agents/run_agents.py는 상대 경로다. 다른 데서 치면 can't open file이 난다
터널	아무 폴더에서나	cloudflared는 현재 폴더를 보지 않는다. 터널 설정을 %USERPROFILE%\.cloudflared\config.yml에서 읽으므로 어디서 쳐도 같다

# 터미널 1 — 저장소 루트로 가서
cd <저장소를 클론한 폴더>        # 예: cd ~/Documents/PrintGuard-AI
conda activate dev
python agents/run_agents.py

# 터미널 2 — 폴더는 상관없습니다
cloudflared tunnel run printguard

cloudflared: command not found가 나면 PATH에 없는 것입니다. 설치 폴더로 옮겨 가서 치거나(Windows 기본값 C:\Program Files (x86)\cloudflared) 실행 파일을 전체 경로로 부릅니다.

cd "/c/Program Files (x86)/cloudflared"      # Git Bash
./cloudflared tunnel run printguard

증상으로 어느 쪽이 꺼졌는지 가릅니다.

증상	꺼진 것
curl http://127.0.0.1:8700/health가 응답 없음	에이전트
로컬은 되는데 https://pg.2taeyoon.com이 530	터널 — 아직 아무 터널도 붙지 않았다는 뜻
로컬도 응답이 없고 https://pg.2taeyoon.com이 502	에이전트 — 터널은 PC까지 닿았는데 8700이 대답을 안 한다
로컬도 터널도 되는데 화면만 안 붙음	CORS(agents/.env의 PG_CORS_ORIGIN_REGEX) 확인

터널을 서비스로 등록해 두기

터널은 에이전트와 달리 수명을 길게 둘 수 있습니다. Windows 서비스로 등록하면 PC를 켤 때 알아서 뜨고, 창을 닫아도 안 죽습니다. 그 뒤로 손으로 켤 것은 에이전트 하나로 줄어듭니다 — 대개 꺼져 있는 쪽이 에이전트인 이유입니다.

관리자 권한 터미널에서 한 번만 합니다. 폴더는 상관없습니다.

cloudflared service install

터널 이름을 따로 줄 필요는 없습니다. 서비스가 %USERPROFILE%\.cloudflared\config.yml을 그대로 읽어 돕니다. 그래서 그 파일을 고쳤으면 서비스를 다시 시작해야 반영됩니다.

확인과 멈춤·되살리기는 서비스로 다룹니다(멈춤·되살리기·해제는 관리자 권한).

sc query cloudflared              # RUNNING인지. 이름을 못 찾으면 sc query state= all | findstr -i cloudflared
net stop cloudflared              # 멈춤
net start cloudflared             # 되살리기
cloudflared service uninstall     # 등록 해제

서비스가 돌고 있으면 cloudflared tunnel run을 따로 치지 마세요. 같은 터널에 두 프로세스가 붙어 요청이 둘로 갈립니다. 긴가민가하면 tasklist | findstr cloudflared로 먼저 셉니다.

테스트: python -m pytest agents -q (122개) 타입·린트·빌드: cd frontend && npx tsc --noEmit && npx eslint app lib && npm run build

This is the beginning of the README. Read the rest at the original. Read the full README ↗