한눈에

표적 구조에서 결합 펩타이드를 설계하고 분자동역학으로 후보를 줄 세운다. 대시보드는 g2에서 제공하고 계산은 작업별 자원과 검증된 런타임에 따라 배정한다. Slurm 및 자동 실행 선택의 적용 상태는 운영 소스·실행 관리를 따른다.

두 갈래의 실행 경로

같은 CLI 를 사람이 부르거나 화면이 부른다.

Claude Code 서브에이전트 6종 ─┐
bin/pepd-* CLI ───────────────┼→ 같은 bin/pepd-* 래퍼 → lib/PepDesigner/
웹 대시보드(코드 오케스트레이터)┘

• bin/pepd-* 래퍼가 conda 환경을 내부에서 켠다 — 손으로 conda activate 할 일이 없다.
• 서브에이전트는 .claude/agents/ 에 있다 — pep-designer(진입) · target-profiler · candidate-builder · binder-designer · job-runner · result-reporter.
• 패키지는 기능별로 갈라져 있다 — api/(외부 DB) · generation/ · scoring/ · docking/ · bindcraft/ · md/ · dashboard/ · cli/ · structure/.

모드가 둘인데 화면은 하나다

웹 대시보드는 denovo 전용이다 — 모드 선택기를 걷어냈다. 구조 예측기는 Boltz-2 가 기본이고 AF2 는 폴백일 뿐이다. 그래서 화면에서 서열 모드를 쓸 수 없다(코드에는 있다).

서버 전제

/data/program/BindCraft/ 는 첫 실행 전에 hg:sysmed 소유로 존재해야 한다(새로 만든 서버라면 한 번의 sudo mkdir && sudo chown). 준비 여부는 pepd-bindcraft --check.

경로·활성화 명령의 정본은 config/setpath.md 다. 기능 스펙과 변경 이력은 config/spec.md, denovo 파이프라인 규격은 config/workflow.md(한국어판 workflow.kr.md).

실행 폴더 규칙

runs/<TARGET>_<시각>/
  target.json  structure/target.pdb
  native/      complex.pdb · receptor.pdb · interface_annotation.json · hotspots.json
  bindcraft/   shard_g<N>/ (설계당 GPU 하나) · final_design_stats.merged.csv · ranked/ · ranked.tsv
  epitopes/ep<k>/   --per-epitope 일 때 에피토프별 하위 실행 (위로 병합)
  md/<design>/ prod.{xtc,tpr,gro} · FINAL_RESULTS_MMPBSA.dat · mmpbsa_decomp/ · rmsd·rmsf·sasa…
  redesign.json · redesign/redesigned.fasta
  figures/     bar_dG · heatmap · timeseries_hotspot · hbond_density · rmsd · rmsf …
  jobs/<kind>.{state,state.json,log,pid}    단계별 상태 — 대시보드는 pipeline.json 으로 굴린다
  report.md

상태가 파일로만 남는 것이 이 설계의 핵심이다 — 대시보드는 상태 파일을 폴링하고, 새로고침해도 진행 중인 작업에 다시 붙는다. GPU 여러 장에 독립 시도를 동시에 띄워 (shard_g<N>) 먼저 목표 개수를 채운 쪽을 쓴다.

대시보드와 인증

bin/pepd-dashboard                 # 로컬 전용 http://127.0.0.1:8011
bin/pepd-dashboard --public        # 0.0.0.0 바인드 (아래 경고)
bin/pepd-dashboard --auth          # 다중 사용자 — 로그인·승인·사용자별 격리

• --auth 없이 띄우면 인증이 전혀 없고 GPU 작업을 띄울 수 있다. 신뢰된 망에서만 열거나 SSH 터널(ssh -L 8011:localhost:8011)을 쓴다.
• 인증 모드는 Google 또는 이메일·비밀번호 로그인, 신규 가입은 관리자가 /admin 에서 승인할 때까지 pending, 실행은 runs/<user_id>/ 로 격리된다.
• 비밀값은 환경에서만 읽는다 — --env-file(기본 .pepd-auth.env, gitignore). SESSION_SECRET 은 필수이고, 없으면 프로세스마다 새로 만드는 대신 기동을 거부한다(그렇지 않으면 재기동마다 전원이 조용히 로그아웃된다).
• Google 로그인은 선택이다 — GOOGLE_CLIENT_* 가 없으면 /auth/google 이 503 을 내고 이메일 로그인만 동작한다. --redirect-uri 는 콘솔의 승인된 URI 와 바이트 단위로 같아야 한다.
• 공개 인스턴스는 *.sysmed.kr 인증서를 /home/hg/.pepd-tls/ 에 복사해 쓴다. 8011 은 경계 방화벽이 막으므로 열려 있는 8081 을 공인 IP 에 바인드한다(같은 8081 을 쓰는 루프백 전용 서비스가 있어 공인 IP 지정이 충돌을 피한다).
• 회사 사이트는 contextBio 통합계정 토큰을 백엔드로 전달한다. lib/PepDesigner/dashboard/firebase_auth.py와 contextbio_auth의 서버 검증을 유지하고, 배포 시 실제 서비스 인증 모드와 승인·사용자별 접근 제한을 확인한다.

자연어 파이프라인 설정

사용자 패널에서 허용된 LLM 모델을 선택하고 텍스트로 파이프라인 구성을 요청한다. 모델 출력은 서버가 허용된 설정 스키마와 사용자 권한을 검증한 뒤 반영한다. 시스템 정보·비밀값 반출, 서버·인증·Slurm 설정 변경, 임의 명령 실행은 허용하지 않는다. 모델 선택이 이러한 권한을 확대하지 않는다. 구체적인 경계는 LLM 운영 규정을 따른다.

알아 둘 함정

• 통과 기준이 조용히 느슨해진다. 기준을 통과한 설계가 없으면 최대 8단계까지 낮춰 다시 거르는데, 리포트에는 언제나 원래의 엄격한 기준이 인쇄된다. 지표 값을 직접 대조해야 한다.
• 화면에는 MM-PBSA 라고 쓰여 있지만 실제로는 MM-GBSA(GB-OBC2)이고 기본 production MD 가 약 100 ps 로 짧으며 엔트로피 항을 계산하지 않는다 — 후보 간 상대 비교용이다.
• 서열이 서버 밖으로 나간다. 서열만 주어 구조를 예측하면 Boltz-2 가 MSA 를 외부 ColabFold 서버에서 받는다. 표적 조회(UniProt·InterPro·STRING·AlphaFold DB·RCSB)도 외부 호출이다.
• 수용체가 450 잔기를 넘으면 핫스팟 중심으로 창을 잘라 쓴다 (GPU 메모리).
• Slurm 작업은 자원 상황에 따라 대기한다. 자동 실행 선택을 적용한 서비스에서도 유휴 조건과 제한을 통과한 작업만 직접 실행하며 실패 시 무제한 로컬 실행으로 전환하지 않는다.
• BLAST DB 는 data/blast_db/human_reviewed 에 미리 지어져 있다 (PEPD_BLAST_DB 로 가리킨다).