Glasshat — 온보딩 종합 보고서

§0TL;DR 핵심 요약

Glasshat은 덱 PDF + GitHub 레포지토리를 입력으로 받아, 6-perspective AI 패널(Six Thinking Hats)이 BMAD 17항목 / 100점 rubric으로 점수를 매기는 비-챗봇 평가 파이프라인. 차별점은 패널이 자기 자신의 편향을 실시간으로 감지하고 자가-교정하는 audit-the-auditor 루프가 화면에서 보인다는 점. 단일 코드베이스로 Qdrant VSD 해커톤(2026-06-01) + Google Cloud Rapid Agent 해커톤 / Arize 트랙(2026-06-11) 양쪽에 다른 narration으로 제출.

§1Glasshat이란

1.1 제품 정의

Glasshat은 artifact-ingesting fair-evaluation agent입니다. 채팅 인터페이스가 아닙니다. 사용자가 두 개의 드롭존(PDF 덱 + GitHub URL)에 자료를 넣으면, 자율적으로 다음 파이프라인을 실행합니다:

1. Ingest — PDF → Gemini multimodal 파싱 → 청크화 → Qdrant 임베딩 / 레포 shallow clone → 정적 휴리스틱 → 샘플 코드 → Qdrant 임베딩
2. Plan — Blue 오케스트레이터가 검수 가능한 plan object 발행 (어떤 hat, 어떤 BMAD 항목, 어떤 기법 적용, 검색 예산 등). 사용자가 plan을 검토/수정 (Human Gate 1)
3. Run Panel — 6 hats가 병렬 실행 (White facts / Red intuition / Yellow value / Black risk / Green creative / Blue synthesis)
4. Audit-the-Auditor — Black hat이 Yellow의 점수 편향 감지 → Blue planner가 Phoenix MCP에 과거 드리프트 조회 → Qdrant Recommendation API로 anti-pattern 앵커 검색 → 점수가 화면에서 자가-교정
5. Score — BMAD 17항목 / 100점 채점, 모든 sub-score에 evidence 부착
6. Report — 서명된 audit trail, 2D radar + 3D 평가 그래프, vector-search 페이지. 사용자가 임의 점수 override 가능 (Human Gate 2)

1.2 왜 "non-chatbot"인가 (Qdrant 룰)

Qdrant VSD 해커톤은 "submissions that are only chatbots are not allowed"가 hard rule입니다. Glasshat의 UI는 드롭존 + 플랜 카드 + 모니터 + 리포트 + 3D 그래프 + 벡터 검색 페이지로 구성되며 채팅 박스가 어디에도 없습니다.

1.3 왜 "agent that does a task"인가 (Rapid Agent 룰)

입력이 프롬프트가 아니라 아티팩트이며, plan → tool use → execute → 사용자 통제 유지 → 결과물 생성 패턴을 만족합니다. Google ADK on Cloud Run + Vertex AI Agent Builder에 등록 + Phoenix MCP 파트너 통합으로 partner-track 자격을 충족합니다.

1.4 fairthon 컨셉 계보 (코드 재사용 아님)

Glasshat의 방법론 — Six Thinking Hats + BMAD rubric + 75 기법 + 3D 그래프 — 는 fairthon.com(동일 팀)의 컨셉에서 파생됩니다. 그러나 그 방법론은 설계/스펙이지 코드가 아닙니다. fairthon 또는 어떤 이전 프로젝트의 소스 코드도 재사용하지 않으며, 본 레포의 모든 코드는 해커톤 기간(2026-05-13 첫 커밋) 내에 새로 작성되었습니다. 양쪽 해커톤의 "all code in period" 룰을 컴플라이언스 합니다.

§2듀얼 해커톤 컨텍스트

2.1 Qdrant VSD "Think Outside the Bot" 2026 (Primary)

2.2 Google Cloud Rapid Agent Hackathon — Arize Track (Secondary, repackaging)

2.3 듀얼 제출 전략 — 단일 엔진, 두 narration

📌 동일 엔진의 ~80% 코드 경로 공유. 차이는 narration + foreground UI + Phoenix UI side-by-side 녹화 여부.

§3의사결정 히스토리

매 결정의 출처(누가) 및 근거를 함께 기록합니다. 사용자(app.2weeks@gmail.com)가 최종 결정자, 5-전문가 패널(Porter/Christensen/Godin/Doumont/Drucker)이 자문, Claude Code가 실행.

3.1 주요 결정 12건 (locked)

§4기술 아키텍처

4.1 스택 한눈에

4.2 BMAD Rubric — 17 항목 / 100 점

4.3 에이전트 토폴로지 (audit loop 포함)

topologyGlasshatRootAgent  // CustomAgent — orchestrator
├─ IngestAgent  // PDF 파서 + 레포 클로너
├─ BluePlannerAgent  // LlmAgent · Gemini 3.1 Pro · thinking=high
├─ HatsPanel  // ParallelAgent (6 hats 병렬)
│  ├─ WhiteAgent    // + Qdrant hybrid + Vertex Grounding
│  ├─ RedAgent
│  ├─ YellowAgent   // + Qdrant hybrid
│  ├─ BlackAgent    // + Qdrant hybrid · must_cite_precedent
│  ├─ GreenAgent
│  └─ BlueSynthesisAgent
├─ AuditLoop  // LoopAgent · max_iterations=2
│  ├─ InconsistencyDetectorAgent  // 3-redundant 감지 union
│  │   ├─ Path 1: Phoenix Online Eval annotation
│  │   ├─ Path 2: Phoenix Custom Python Evaluator
│  │   └─ Path 3: Black hat counter-claim
│  ├─ PhoenixConsultantAgent  // + Phoenix MCPToolset + Qdrant Recommend
│  │   ├─ get-experiment-by-id // 드리프트 집계
│  │   ├─ get-span-annotations // 증빙 체인
│  │   ├─ get-dataset-examples // 앵커 프로필
│  │   └─ qdrant.recommend(positive, negative, "average_vector")
│  └─ ScoreCalibrationAgent  // clip(pred - 0.8*delta, p25, p75)
├─ BMADScorerAgent  // + group_by + context cache
└─ ReportAssemblerAgent  // Firestore audit + SSE 800ms-paced

전체 토폴로지·시퀀스·페이즈별 배포 매트릭스는 docs/architecture.md 및 docs/wow-moment-design.md §4 참조.

§5Audit-the-Auditor 모먼트

전체 전략의 린치핀입니다. 양쪽 데모의 wow factor가 같은 엔지니어링을 다른 narration으로 렌더링합니다.

5.1 5단계 분해 + 타당성 (모두 spike-검증)

5.2 MCP 호출 chain (consultation 모먼트, 4 parallel calls, <800ms)

mcp · python# Phoenix MCP via ADK MCPToolset (Stdio transport)
from google.adk.tools.mcp_tool import MCPToolset, StdioConnectionParams
from mcp import StdioServerParameters

phoenix_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="npx",
            args=["-y", "@arizeai/phoenix-mcp@latest",
                  "--baseUrl", os.environ["PHOENIX_BASE_URL"],
                  "--apiKey", os.environ["PHOENIX_API_KEY"]],
        ),
        timeout=30.0,
    ),
)

# Consultation 모먼트의 4 parallel calls (Spike A 측정: 17-27ms each)
results = await asyncio.gather(
    phoenix_mcp.call("get-experiment-by-id",
        experiment_id="glasshat-calibration-v1",
        filters={"hat": "yellow", "criterion": "A1",
                 "evidence_depth_bucket": "<0.4"}),
    phoenix_mcp.call("get-span-annotations",
        span_ids=[yellow_a1_span_id], project_identifier="glasshat-prod"),
    phoenix_mcp.call("get-dataset-examples",
        dataset="calibration_corpus_v1", limit=3,
        filter={"hat": "yellow", "evidence_depth_bucket": "<0.4"}),
    qdrant_client.recommend(
        collection="past_evals",
        positive=anchor_overconfident_ids,
        negative=anchor_accurate_ids,
        strategy="average_vector",
        limit=3),
)

5.3 Calibration 공식 (Spike D 검증)

pythondef calibrate(predicted: float, phoenix_findings: dict, anchors: list) -> float:
    mean_delta = phoenix_findings["mean_delta"]    # e.g. 1.2 (over-confident bias)
    raw = predicted - 0.8 * mean_delta            # conservative pull
    delta = raw - predicted
    delta = max(-2.0, min(2.0, delta))           # ±2.0 absolute cap
    candidate = predicted + delta
    p25, p75 = anchors["p25"], anchors["p75"]
    return max(p25, min(p75, candidate))      # clip to anchor band

# Spike D synthetic test (50 train, 50 holdout):
#   Uncalibrated MAE: 0.517
#   Calibrated MAE:   0.334  → 35.4% improvement
#   Yellow A1 low-evidence bucket: 1.476 → 0.505 (66% reduction in the target bucket)

5.4 사전-시드 의존성 (★ 데모 시연 차단요인)

§633 APPLY · 9 STRETCH · 5 CUT — Apex Pass 결정

Qdrant / Phoenix / Gemini 3 / Google ADK 각 스택의 고급 기능 47개를 명시적으로 결정. 자세히는 docs/technical-apex-features.md.

6.1 APPLY 33개 (v1 필수)

6.2 STRETCH 9개 (Phase 1/2 일정 허용 시)

• Qdrant: 1.4 Discovery API · 1.8 ColBERT multi-vector · 1.10 cross-collection lookup
• Phoenix: 2.8 Prompt versioning · 2.10 Agent trajectory evaluator
• Gemini: 3.5 multi-modal single-call ingestion · 3.7 Code execution tool (메모리 잘 남음)
• ADK: 4.7 before/after agent callbacks · 4.12 Plugins for guardrails

6.3 CUT 5개 (v1 명시적 제외)

• Qdrant: 1.9 DBSF (RRF 충분) · 1.11 HA/snapshots/sharding (운영 우려, 심사 무관)
• Gemini: 3.11 long-context stuffing (anti-pattern)
• ADK: 4.10 ADK Eval framework (Phoenix evals와 중복) · 4.11 A2A protocol (May 2026 immature)

§77-Spike 검증 결과 (모두 PASS)

Phase 1 코드 작성 전, 선택된 기술 스택이 실제로 작동하는지 검증한 7개 spike test. 자세히는 docs/spike-results.md, 스크립트는 spikes/0[1-7]_*.py.

7.1 결정적 발견

• ADK MCPToolset 정확한 와이어링 발견 (문서엔 미명시): MCPToolset(connection_params=StdioConnectionParams(server_params=mcp.StdioServerParameters(...))) — 두 단계 wrap이 정답
• Spike C에서 7 Phoenix spans 자동 캡처 — 데모에서 "에이전트가 자기 reasoning을 본다" narrative가 OpenInference 자동 instrumentation으로 추가 코드 없이 시각화
• Calibration 수학 실제 작동 — Yellow A1 bias +1.4 합성 → mean_delta 1.453 정확히 회수
• Event는 EventActions() 필수 (None 거부됨)
• Annotations은 dict 반환 (SDK signature와 다름) → helper로 안전 접근
• MCP cold-start 1.7-2.1s (npx spin-up). 한 세션 재사용 시 sub-100ms — AuditLoop가 같은 toolset 세션 유지

7.2 환경 + 비용

§8524 Gemini 3 코퍼스 전략

gemini3.devpost.com의 4,499개 공개 제출작에서 stratified 샘플 524개를 추출, Glasshat의 calibration corpus로 사용.

8.1 왜 이 코퍼스인가

• 30-90× 더 큰 통계 power (기존 "50-150 random Devpost projects" 대비)
• 모든 프로젝트가 Gemini 3 스택 — Glasshat 자체와 in-distribution
• 2025-Dec/2026-Feb 최근 데이터 — calibration 신선
• required 자산: Devpost 설명 + public GitHub repo + 데모영상 — Glasshat이 평가하는 형식과 정확히 동일
• 공개된 심사 가중치 — Tech 40% · Innovation 30% · Impact 20% · Presentation 10% → Glasshat BMAD 4축에 거의 1:1 매핑
• 24+ winners ribbon으로 ground-truth 라벨 확보

8.2 스크레이핑 파이프라인 (Phase 1.12)

1. robots.txt + 1 RPS throttle 확인
2. 188 페이지 × 24 = 4,499 인덱스 페치 → seed/gemini3-index.jsonl
3. Stratified sampling: 24+ winners + 500 random non-winners → seed/gemini3-sample-524.jsonl
4. 524개 디테일 페이지 페치 (1 RPS, ~9분)
5. GitHub repo URL 있는 것만 필터 (예상 70-90%)
6. 각 repo shallow clone + README + 정적 휴리스틱
7. Glasshat 파이프라인 실행 (Flash-Lite, batch prediction, ~6-12시간)
8. OpenInference 자동 → Phoenix Cloud glasshat-prod
9. Phoenix Experiment glasshat-calibration-v1 집계
10. Held-out 검증: calibrated MAE ≤ 0.85 × uncalibrated MAE

8.3 컴플라이언스

8.4 데모 메타-narrative (Qdrant 데모만)

§9데모 스크립트 — 양쪽 3:00

두 데모 모두 ≤3분 / 영어 캡션 / no voice-over / 800ms-paced wow beats. 자세히는 docs/max-wins-plan.md §5.

9.1 Qdrant VSD 데모 — 7 wow/kick beats

9.2 Rapid Agent / Arize 데모 — 8 wow/kick beats

§10리스크 + Mitigation

§11정직한 수상 확률 추정

5-전문가 패널 + 룰 분석 + 과거 우승작 패턴 + spike 검증 기반의 정직한 추정. Marketing 표현 금지.

11.1 더 끌어올릴 단일 가장 큰 레버

11.2 의식적으로 인정하는 한계

• top-3 ≠ 1st-place. 위 확률은 "심사관 top-3 안에 들 가능성"이며, 1등 자체 확률은 더 낮음.
• Combined expected value (1st-place equiv): pre-plan ≈ $1.7K, post-plan ≈ $4.2K — order-of-magnitude reasoning이지 financial forecast 아님.
• 2026 Qdrant Best-in-Category 스폰서 미공개 → upside potential 미포함.
• 심사관의 주관적 lineage 평가(fairthon)는 확률에 반영 안 됨.

§12Phase 1 빌드 진입점

모든 계획 + 검증 완료. Phase 1 (로컬 E2E) 코드 작성 진입 준비됨. 우선순위 + 의존성 명시:

총 예상 ~6,000 lines. 사용자 "시간 무시" 지시이므로 캘린더 제약은 적용 안 함 — 단 Qdrant 6/1 마감과 Rapid Agent 6/11 마감은 자연스럽게 ordering 결정.

12.1 Phase 1 완료 기준

§13신규 팀원 첫날 체크리스트

이 보고서를 받고 처음 90분에 해야 할 액션. 한 항목씩 따라가면 됩니다.

13.1 환경 (15분)

• 본 보고서 끝까지 읽기 (15분)
• 다음 파일도 읽기:
  • README.md — 한 페이지 컨셉 요약
  • docs/max-wins-plan.md §0 (one paragraph) + §12 (decisions) — 5분
  • docs/wow-moment-design.md §1 + §4 (agent topology) — 5분

13.2 로컬 환경 확인 (15분)

bash# Working directory (Glasshat 리네이밍 진행 중 — 폴더는 아직 panelyst)
cd ~/Documents/GitHub/glasshat

# 1) 환경 도구 확인
python3 --version  # 3.12.x 권장
node --version     # v24+
uv --version       # https://docs.astral.sh/uv/

# 2) .env 파일 확인 (이미 .env.backup-pre-rename 백업 존재)
grep -c "GLASSHAT_" .env  # 14 (post-rename)

# 3) GCP credentials 확인
ls -l ~/.config/gcloud/panelyst-dev-sa-key.json  # mode 600
export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/panelyst-dev-sa-key.json
export GOOGLE_CLOUD_PROJECT=panelyst-hackathon  # GCP 프로젝트 ID는 KEEP

13.3 Spike test 재현 (30분)

bashcd spikes/
uv sync                       # 약 60-90초

# 가장 짧은 spike부터:
uv run python 02_spike_b_adk_loop.py        # ~5초, no API calls
uv run python 04_spike_d_calibration_toy.py # ~1초, no API calls
uv run python 05_spike_e_sse_animation.py   # ~5초
uv run python 01_spike_a_phoenix_mcp_smoke.py    # ~30초 (Phoenix in-process + npx)
uv run python 07_spike_g_phoenix_annotations.py  # ~30초
uv run python 06_spike_f_phoenix_online_evals.py # ~30초
uv run python 03_spike_c_adk_mcptoolset.py       # ~60초 (~$0.0001 Vertex call)

# 모든 결과: spikes/results/spike_*.json (overall_pass=true 확인)

13.4 핵심 의사결정 이해 확인 (15분)

다음 질문에 즉답할 수 있어야 합니다:

• Glasshat의 wow 모먼트를 30초 안에 설명할 수 있는가?
• 왜 Qdrant primary이고 Arize secondary인가?
• 왜 ADK인가, Agent Builder가 아니라?
• 3-redundant detection의 세 경로는 무엇인가?
• 524 코퍼스는 어디서 오는가, 왜 stratified인가?
• Phoenix MCP 4-call chain은 어떤 도구들을 호출하는가?
• Rapid Agent Tech Implementation이 왜 타이브레이커 1번인가?
• Gemini 3 thinking_level이 hat tier마다 어떻게 설정되었는가?

답 못 하는 항목이 있으면 해당 문서 다시 읽기 (위 13.1 참조).

13.5 의문 + 의견 (15분)

다음 영역에서 자유롭게 push back / 추가 아이디어 제시:

• Apex Pass 9 STRETCH 기능 중 Phase 1에 promotion할 만한 것?
• Wow 모먼트의 추가 backup beat 제안?
• Qdrant 데모의 0:30-1:00 슬롯이 충분히 dense한가?
• 524 corpus 외에 추가 calibration 데이터 소스?
• 3D 그래프의 r3f 디자인 제안?
• 리스크 #4 (audit 모먼트 가독성)에 대한 추가 mitigation?

13.6 첫 작업 (옵션)

다음 중 하나를 선택해서 Phase 1 진입 — 모두 Phase 1.X의 자기 완결 작업:

§14참고 파일 인덱스

14.1 권위 문서 (반드시 읽기)

14.2 Spike 스크립트 (실행 + 재현 가능)

• spikes/01_spike_a_phoenix_mcp_smoke.py — Phoenix in-process + MCP discovery
• spikes/02_spike_b_adk_loop.py — LoopAgent + escalation
• spikes/03_spike_c_adk_mcptoolset.py — ADK + Phoenix MCPToolset
• spikes/04_spike_d_calibration_toy.py — Calibration policy
• spikes/05_spike_e_sse_animation.py — SSE timing
• spikes/06_spike_f_phoenix_online_evals.py — Online Eval OSS
• spikes/07_spike_g_phoenix_annotations.py — Annotation R/W
• spikes/README.md — spike 인덱스
• spikes/results/*.json — 실행 결과 (모두 overall_pass=true)

14.3 영구 메모리 (Claude Code 세션 간 자동 로드)

경로: /Users/kimsejun/.claude/projects/-Users-kimsejun-Documents-GitHub-hackathon-submissions/memory/

• MEMORY.md — 인덱스
• panelyst-project.md — Glasshat (formerly Panelyst) 마스터 (post-rename 상태 반영)
• glasshat-max-wins-decisions.md — 12 lock된 결정
• glasshat-technical-apex.md — 33 APPLY decision 결정
• glasshat-spike-validation.md — 7-spike 결과
• gemini-model-panel-verified.md — Gemini 3 모델 측정 + gotchas
• gcp-panelyst-hackathon.md — GCP 셋업 (KEEP "panelyst-hackathon" name)
• qdrant-vsd-hackathon.md · rapid-agent-hackathon.md · qdrant-collection-design.md · fairthon-lineage.md · hackathon-pipeline-2026-may-jun.md
• user-*.md · production-safety-rules.md — 사용자 작업 선호 + 안전 룰

14.4 외부 출처 (URL)

• Qdrant VSD: try.qdrant.tech/hackathon-vsd · 제출 form forms.gle/YDQ2TDUi8MqS9Vx28
• Rapid Agent: rapid-agent.devpost.com · 룰 /rules · Arize /details/arize-resources
• Qdrant 2025 winners: qdrant.tech/blog/vector-space-hackathon-winners-2025
• Phoenix MCP README: github.com/Arize-ai/phoenix
• Arize Gemini hackathon starter kit: github.com/Arize-ai/gemini-hackathon
• ADK LoopAgent: adk.dev/agents/workflow-agents/loop-agents
• ADK Custom agents: adk.dev/agents/custom-agents
• Gemini 3 hackathon (corpus source): gemini3.devpost.com

질문이 있으면 사용자(app.2weeks@gmail.com)에게 직접 또는 새 세션에서 cd ~/Documents/GitHub/glasshat && /handon으로 이어가세요.
본 보고서는 2026-05-15 KST 기준 상태이며, 이후 진행은 git log + 메모리 + handoff doc으로 추적됩니다.