공개 기술 문서

캥거루 점프 엔진 데이터·모델·공개 조건 설명서

이 문서는 현재 공개판이 어떤 원천을 읽고, 어떤 자료만 검수 입력으로 반영하며, 어떤 조건에서 새 예측판을 공개할 수 있는지 설명합니다. 점프의 정치학은 합성 페르소나 기반 예측 시뮬레이션입니다. 실제 투표 결과나 여론조사를 대체하지 않으며, 결과를 읽을 때는 데이터 신뢰도와 지역별 품질 라벨을 함께 확인해야 합니다.

엔진 버전

V1.0.5

kangaroo-jump-engine-v1.0.5

공개 가능 상태

여론조사 반영 공개 가능

여론조사 반영

합성 페르소나

1,000,000명

개별 행은 공개하지 않음

인구 보정 총량

44,519,085명

공식 인구 기준

검수 후보

643건

출마 중 626건

후보 반영 지역

256개

현재 시·도지사 중심

검수 여론조사

12건

11건 검수 대기

뉴스·공약

74건 / 176명

메타데이터와 digest만 사용

데이터 파이프라인

소스별 공개 범위와 반영 흐름을 따로 봅니다.

공개 조건

후보 반영, 여론조사 반영, 보류 상태를 판정 기준 중심으로 봅니다.

버전 정책

V1.0.5부터 시작하는 패치·마이너·메이저 업데이트 규칙을 정리합니다.

공개 데이터 계약

공개 스냅샷과 후보·근거 요약의 숫자 의미를 봅니다.

배포 저장 구조

계정별 실험실 저장, private raw bucket, 공식 스냅샷 분리 원칙을 봅니다.

캥거루 점프 엔진

엔진 작동 흐름, 출력 항목, LLM 사용 범위를 문서 안에서 이어서 봅니다.

처음 읽는 순서

이 서비스는 한 화면의 순위표보다 데이터의 상태와 변화 이력을 함께 보는 방식에 가깝습니다. 아래 순서로 읽으면 예측값, 근거 데이터, 가상 실험, 공개 조건을 섞지 않고 해석할 수 있습니다.

예측을 먼저 봅니다

최신 스냅샷의 지도, 승리확률, 득표율·득표수를 확인합니다. 품질 라벨이 기본자료 예측이나 자료 대기라면 숫자를 확정 판세처럼 읽지 않습니다.

데이터에서 근거를 엽니다

후보, 공약, 여론조사, 인구 기준, 과거 선거 데이터셋을 테이블로 확인합니다. 필요한 경우 이전 스냅샷으로 전환해 같은 항목의 과거 상태와 비교합니다.

실험실에서 가정을 분리합니다

기사, 여론조사 변화, 후보 사퇴 같은 가상 조건은 실험실에서만 다룹니다. 저장한 조건은 합성 가정 라벨로 표시되며 공식 사실로 승격되지 않습니다.

문서에서 한계를 확인합니다

소스 데이터, 신뢰도 라벨, 공개 조건, 엔진 계산 원칙을 확인해 어떤 입력이 결과를 강하게 움직였고 어떤 입력은 참고 신호인지 구분합니다.

페이지별 사용법

각 페이지는 같은 공개 스냅샷을 서로 다른 관점에서 보여줍니다. 예측 화면은 결과를, 데이터 화면은 근거 행을, 실험실은 가정에 따른 변화량을, 문서는 판단 기준을 담당합니다.

예측

열기

현재 또는 과거 스냅샷의 결과를 지도와 지역 상세로 봅니다. 지역을 선택하면 1위 정당, 승리확률, 득표율·득표수, 후보·공약·여론조사 coverage가 함께 표시됩니다.

스냅샷 화살표로 이전 결과와 최신 결과를 비교
품질 라벨이 낮은 지역은 숫자보다 근거 공백을 먼저 확인
자료 부족으로 비활성화된 지역은 예측을 보류

데이터

열기

예측 화면이 읽은 공개 데이터셋을 raw에 가까운 표로 확인합니다. 후보, 근거, 공약, 여론조사, 과거 선거, 소스 목록을 섹션별로 열고 페이지네이션으로 탐색합니다.

상단 요약은 현재 스냅샷 상태
하단 테이블은 행 단위 공개 근거
스냅샷 전환으로 과거 데이터셋 상태 확인

실험실

열기

뉴스 사건, 여론조사 변화, 투표율 변화, 후보 상태 변화를 가정해 시뮬레이션합니다. 대화 입력으로 가정을 정리하고 저장한 뒤 실행하면 기준 스냅샷과 변화량을 비교합니다.

가상 입력은 합성 가정 라벨로만 사용
첨부 파일 원본은 서버로 보내지 않음
자료 부족 지역은 실행 버튼이 비활성화

AI도우미

열기

강걸우 페르소나 AI도우미가 공개 문서와 스냅샷 요약을 근거로 답합니다. 특정 지역, 후보, 데이터셋 이름을 넣어 질문하면 더 좁은 범위로 설명합니다.

공식 사실은 확인된 공개 컨텍스트 안에서만 답변
원문 기사·비공개 작업 자료는 노출하지 않음
불확실한 항목은 미확인으로 표시

문서

열기

서비스의 데이터 출처, 신뢰도 라벨, 공개 JSON 계약, 엔진 이론, 공개 조건, 검증 기준을 설명합니다. 결과를 인용하거나 공유하기 전 기준 문서로 사용합니다.

소스 데이터와 공개 경계 확인
신뢰도 라벨 의미 확인
공개 조건과 버전 정책 확인

결과 해석 규칙

숫자는 그 자체보다 어떤 데이터와 품질 상태에서 나왔는지가 중요합니다. 아래 항목은 예측 화면과 데이터 화면을 함께 볼 때의 기본 해석 규칙입니다.

승리확률

현재 공개 스냅샷의 모델상 우세 확률입니다. 선거 결과 확률이나 여론조사 지지율이 아닙니다.

득표율·득표수

득표율은 후보별 선택 확률을 0.1% 단위로 표시하고, 득표수는 선거인수와 투표율 가정을 곱한 예상 투표자 수에서 계산합니다.

품질 라벨

지역 결과의 근거 수준입니다. 엔진 예측, 부분 보정, 기본자료 예측, 자료 대기 순으로 해석합니다.

신뢰도 라벨

데이터셋 자체의 출처와 필드 완성도입니다. 공식·고신뢰, 검증 공개, 참고 신호, 합성 가정으로 나뉩니다.

자료 부족

후보 비교, 선거인수, 득표 분포 기준이 없으면 해당 지역은 예측과 실험실 실행을 비활성화합니다.

실험실 결과

화면 반영

공약 영역별 요약

신뢰도: 검증 공개

데이터 신뢰도 라벨

새 데이터가 들어와도 사람의 확인을 기다리는 blocker로 멈추지 않습니다. 대신 엔진은 출처의 공식성, 공개 필드의 완성도, coverage, 최신성, 모델 입력 성격을 기준으로 네 단계 라벨을 붙입니다. 라벨은 예측 결과를 더 강하게 주장하기 위한 장치가 아니라, 사용자가 데이터의 역할과 한계를 빠르게 구분하기 위한 공개 표시입니다.

공식·고신뢰

high

공식 기관 자료이거나 공개 계약의 필수 필드, 출처, 기준 시점, coverage가 모두 맞는 데이터입니다.

예측 결과와 공개 수치의 기준값으로 사용합니다.

검증 공개

medium

공개 출처와 필수 메타데이터가 있으나 coverage, 최신성, 해석 범위에 제한이 있는 데이터입니다.

예측 보정과 설명에는 쓰되 품질 라벨과 함께 표시합니다.

참고 신호

low

뉴스 메타데이터, 검색 결과, 공약 요약처럼 방향성은 주지만 단독 사실로 쓰기 어려운 신호입니다.

지역 설명과 이슈 민감도 보조 신호로만 사용합니다.

합성 가정

synthetic

NVIDIA 합성 페르소나처럼 실제 개인이 아니라 대표 집단 계산을 위한 합성·모형 입력입니다.

집계 시뮬레이션과 보정 기준으로만 사용하고 개인 추론에는 쓰지 않습니다.

데이터 반영 흐름

원천 확인

선관위, 선거여론조사심의위, 인구 기준, 뉴스·공약 요약을 원천별로 분리해 확인합니다. 현재 공개 스냅샷 기준 수집 이벤트는 27건입니다.

검수된 후보 반영

공식 근거가 확인된 후보만 공개 후보 수에 들어갑니다. 현재 검수 후보는 643건, 출마 중 후보는 626건, 사퇴·이력 보존 항목은 17건입니다.

인구 기준 보정

합성 페르소나 1,000,000명을 공식 인구 기준에 맞춰 집계합니다. 현재 인구 기준은 공식 인구 기준이고, 보정 총량은 44,519,085명입니다.

여론조사 공개 요건 확인

반영 지역

14/14

이 선거 종류는 후보 기준 공개 조건을 충족합니다.

공개 데이터 계약

공개 웹은 검수된 정적 스냅샷만 읽습니다. 핵심 데이터는 예측 패키지, 후보 목록, 근거 요약, 스냅샷 업데이트 내역이며 각 항목은 공개 가능한 집계값만 포함합니다.

데이터 계약 자세히 보기

각 공개 데이터의 현재 숫자와 보류해야 하는 숫자를 분리해 설명합니다.

현재 핵심 계약

공개 예측 패키지는 17개 시·도, 17개 광역 집계, 220개 시·군·구 표면을 포함하고, 공개 반영 여론조사는 현재 12건입니다.

배포와 계정별 시나리오 저장 구조

Pro 전환의 첫 단계는 결제가 아니라 저장형 실험실입니다. Supabase Auth로 사용자를 구분하고, Postgres에는 시나리오 프로젝트·입력·컴파일된 이벤트·실행 이력을 저장합니다. 원본 첨부와 OCR 원문은 private Storage에만 두며, 공개 스냅샷과 사용자 실험 run은 서로 덮어쓰지 않습니다.

공식 공개 스냅샷

`public/data` 계약을 유지합니다. 비로그인 사용자와 공개 화면은 public-safe 집계 JSON만 읽고, raw 원문이나 사용자 시나리오 데이터는 볼 수 없습니다.

사용자 시나리오 저장소

로그인 사용자는 `scenario_projects`, `scenario_inputs`, `scenario_events`, `scenario_runs` 단위로 가정을 저장합니다. 실행 요청은 queued 상태로 짧게 저장되고, 별도 worker가 private 결과 테이블을 채웁니다. 이 결과는 private assumption이며 공식 예측으로 승격되지 않습니다.

로그인 방식

실험실은 이메일 magic link를 항상 fallback으로 유지합니다. Google/Kakao 로그인은 Supabase provider가 설정된 배포 환경에서 동작하고, Kakao 이메일 동의가 부족하면 이메일 링크로 돌아갈 수 있게 안내합니다.

Worker 운영

scenario run은 요청 중 직접 계산하지 않고 `queued`로 남깁니다. 운영 환경에서는 server-side worker, cron, 또는 trusted job runner가 service-role key를 들고 public-safe 결과만 저장합니다.

Private Raw Store

뉴스 캡처, 첨부 파일, OCR 원문, 외부 API 원문은 `scenario-raw-assets` private bucket에 저장합니다. 공개 URL은 만들지 않고 소유 사용자에게만 짧은 signed URL을 발급합니다.

이번 범위 제외

Stripe, 구독 tier, paid quota, pricing page는 지금 만들지 않습니다. 운영 보호를 위한 기본 rate/storage 제한은 계정 저장 안정화 이후 별도로 둡니다.

저장소 문서 `docs/deployment-data-architecture.md`와 `supabase/schema.sql`에는 배포 시 적용할 상세 스키마와 private bucket 운영 원칙이 함께 기록되어 있습니다.

캥거루 점프 엔진

합성 페르소나 기반 예측 엔진 V1.0.5

캥거루 점프 엔진은 개별 유권자를 추론하지 않고, 공개 데이터와 합성 페르소나 집계를 결합해 지역·후보 단위의 판세 변화를 계산합니다. 별도 엔진 페이지를 만들기보다 이 문서 안에서 데이터 계약, 공개 조건, 한계를 함께 읽도록 통합했습니다.

엔진 실행 상태

검증 리포트만 생성

공개 가능 상태

여론조사 반영 공개 가능

인구 기준

공식 인구 기준

반영 여론조사

12건

출마 중 후보

626건

엔진 작동 흐름

데이터 고정

예측 회차마다 후보, 여론조사, 인구 기준, 뉴스 메타데이터, 공약 digest를 스냅샷으로 고정합니다. 사용자는 최신판뿐 아니라 과거 스냅샷도 같은 계약으로 비교할 수 있습니다.

공식 인구 보정

합성 페르소나를 18세 이상 지역·성별·연령대 목표 셀에 맞춰 재가중합니다. 득표율은 이 보정된 모집단과 예상 투표자 구성비 위에서 계산됩니다.

과거 선거 기준선

2018/2022 지방선거 등 공개 가능한 과거 선거 결과를 지역별 기준값으로 두고, 후보·정당·지역 구도를 별도 신호로 분리합니다.

후보·공약·뉴스 신호화

후보 이력, 공약 영역, 뉴스 사건은 경제, 주거, 교통, 복지, 안보, 노동, 기후 같은 이슈 신호로 바뀝니다. 뉴스는 원문 전문이 아니라 메타데이터와 요약 신호만 사용합니다.

확률 집계와 불확실성

LLM은 설명과 구조화에 제한적으로 쓰고, 최종 화면 값은 재현 가능한 확률 집계로 산출합니다. 결과에는 quality flag와 백테스트 기준 오차를 함께 둡니다.

여론조사 반영 미리보기

후보 스냅샷

available

여론조사 반영

여론조사 반영 미리보기 준비됨

반영 지역

1개

수치 변화

수치 변화 미계산

검수 여론조사가 표시 요건을 통과해 공개 전 비교 미리보기를 만들 수 있습니다.

지금 공개판은 여론조사 반영입니다. 표시 요건을 충족하지 않은 여론조사나 검수 전 후보 자료는 화면 예측값을 직접 움직이지 않고 신뢰도 라벨과 공개 조건 설명에만 남습니다.

엔진 출력 항목

공개 화면에는 아래 항목을 그대로 노출하지 않고, 지역별 득표율·득표수·승리확률·불확실성·주요 설명 요인으로 다시 요약합니다.

페르소나 집계 -> {
  투표할_가능성,
  연령대별_투표자_가중치,
  후보별_선택_가능성[],
  이슈_성향,
  뉴스_민감도,
  불확실성_범위,
  설명_요인
}

LLM 사용 지점

공약·뉴스 요약, 대표 집단 해석, 실험실 설명 생성에 제한합니다. 최종 판세는 재현 가능한 집계로 계산합니다.

오차와 불확실성

백테스트 참조오차와 지역별 quality flag를 함께 표시해 확정 결과처럼 보이지 않게 합니다.

공개 원칙

출처, 데이터 기준 시각, 모델 버전, 스냅샷 변경 이력을 공개하고 원문·비공개 작업 자료는 노출하지 않습니다.

엔진에 적용되는 이론과 계산 조건

캥거루 점프 엔진은 LLM에게 개별 유권자를 추론하게 하지 않습니다. LLM은 공약·뉴스·대표 집단 설명을 구조화하는 데 제한적으로 쓰고, 공개 예측값은 재현 가능한 지역/후보/페르소나 확률 집계로 계산합니다. 현재 backtest 참조오차는 14.04%p이며, 이 값은 결과를 좁은 확정 예측처럼 보이지 않게 하는 불확실성 기준으로 사용합니다.

회고적 투표

현역·정권·지역 행정 성과 평가가 기본 후보 선택 확률에 영향을 준다는 가정입니다. 과거 선거 baseline과 후보자 효과를 분리해 반영합니다.

경제투표

물가, 일자리, 부동산, 지역 개발 뉴스는 직업·주거·연령 집단마다 다르게 작동합니다. 뉴스는 원문이 아니라 공개 가능한 메타데이터와 요약 신호로만 쓰입니다.

정당 선호와 지역주의

2018/2022 지방선거 결과를 지역별 정당 기준값으로 두고, 영남·호남·수도권·충청 등 장기 지역 구도는 별도 계층 효과처럼 취급합니다.

후보자 효과

현직 여부, 후보 이력, 사퇴/이력 보존 상태, 공약 coverage, 후보 근거 자료의 검수 상태를 후보별 가감 요인으로 둡니다.

이슈 소유권

정당이나 후보가 강점을 가진 정책 영역에서는 같은 공약·뉴스 신호가 더 크게 움직일 수 있습니다. 다만 검수 전 뉴스는 직접 publish 요인이 아닙니다.

투표율 선택 편향

득표율은 선호뿐 아니라 누가 투표하는지에 따라 바뀝니다. 연령대별 투표자 구성비와 turnout probability를 후보 선택 확률과 분리해 계산합니다.

부동층·불확실성

정당 선호가 약하거나 뉴스 민감도가 높은 페르소나 집단은 변동 가능성이 큰 층으로 두고, 결과에는 backtest error와 quality flag를 함께 붙입니다.

공개 조건

기존 예측 유지

hold_existing_forecast

검수 후보 coverage와 검수 여론조사가 모두 부족하면 기존 공개 예측판을 유지합니다.

후보 정보 기준 공개 가능

publish_candidate_snapshot

검수된 후보 반영 범위가 충분하고 공개 안전 검증이 통과하면 후보 정보 기준 공개가 가능합니다.

여론조사 반영 공개 가능

publish_poll_adjusted_snapshot

검수된 여론조사가 있고 공개 표시 요건이 통과해야 여론조사 반영 공개가 가능합니다.

검수 필요

blocked_needs_review

검수 대기 자료만 있거나 필수 항목이 부족하면 새 예측판 공개를 보류합니다.

현재 gate 판정

검수된 여론조사가 있고 공개 표시 요건도 모두 충족했습니다.

공개 안전 검증

통과

여론조사 표시 요건

통과

수동 강제 공개

미사용

버전 정책: 캥거루 점프 엔진 V1.0.5

이번 문서화 기준부터 엔진 표기는 V1.0.5에서 시작합니다. 화면에는 사람이 읽는 V1.0.5를 표시합니다. 버전은 semver처럼 운영하되, 선거 모델에서 의미가 큰 변경일수록 앞자리로 올립니다.

패치 버전

1.0.5 → 1.0.6

오탈자, 한글화, UI 레이블, 문서 보강, 검증 메시지처럼 공개 계약을 바꾸지 않는 수정

마이너 버전

1.0.5 → 1.1.0

새 데이터 입력 경로, 새 검수 리포트, 공개 조건 추가처럼 하위 호환되는 기능 확장

메이저 버전

1.0.5 → 2.0.0

forecast package 계약, 공개 API, 핵심 모델 구조, publish gate 의미가 바뀌는 변경

검증 기준

데이터 반영 전

원천과 기준 기간이 확인됨
검수 전 자료가 공개 예측에 섞이지 않음
후보·여론조사·인구 기준의 반영 범위가 분리됨

새 예측판 공개 전

공개 안전 검증 통과
품질 라벨과 불확실성 표시 유지
업데이트 시각과 변경 입력 요약 표시

여론조사 반영 전

공개 표시 요건 확인
표본·기관·조사기간 등 필수 항목 확인
검수 대기 자료는 보류 상태 유지

인구 기준 반영 전

공식 출처와 기준 기간 확인
필수 지역·연령·성별 범위 충족
행 단위 원자료는 공개하지 않음

공개 금지 항목

원문 작업 자료, API key, cookie, signed URL, raw HTML, 뉴스 전문, 검수 전 원문 일부, 개별 페르소나 행, 특정 개인의 정치 성향 추정값은 공개하지 않습니다.