k-persona

k-persona — Nemotron-Personas-Korea CLI (Node.js)

Python 버전의 Node.js/TypeScript 포팅. 동작·출력이 동일합니다 — 같은 SQL·DuckDB 엔진·hash() 시드 샘플링을 쓰기 때문에, 같은 조건·시드면 동일한 페르소나를 선택하고 브리프도 바이트 단위로 일치합니다.

한국 인구통계 분포를 반영한 합성 페르소나 100만 명(nvidia/Nemotron-Personas-Korea)에서 조건에 맞는 페르소나를 골라 서브에이전트에 주입할 role-play 브리프로 내보냅니다.

빠른 시작 (npx)

설치 없이 바로 실행:

npx k-persona setup                       # 데이터셋 9개 샤드(~2GB) 다운로드
npx k-persona sample --province 서울 --age 30-39 -n 5 --seed panelA

전역 설치하면 persona 명령으로도 쓸 수 있습니다:

npm i -g k-persona
persona sample --match 등산 -n 3

데이터 위치는 PERSONA_DATA_DIR 환경변수 또는 --data-dir 플래그로 바꿀 수 있습니다. (첫 실행 시 @duckdb/node-api 네이티브 바이너리를 받으므로 다소 시간이 걸릴 수 있습니다.)

소스에서 개발/빌드

npm install
npm run build            # TypeScript → dist/
node dist/bin.js setup
# 또는 빌드 없이 개발 모드:  npm run persona -- setup

에이전트 사용 패턴 (핵심)

1. persona values <컬럼>          # 필터에 쓸 정확한 한국어 값 확인
2. persona stats [필터] --by ...  # 세그먼트 크기/분포 점검
3. persona sample [필터] -n N --seed S   # 페르소나 N명 → role-play 브리프
4. 브리프 1개 = 서브에이전트 1명에 주입 → 그 인물로서 검증 수행
5. 결과 집계

--seed 고정 시 같은 패널을 재현할 수 있어, 제품을 고친 뒤 동일 사용자군으로 재검증할 수 있습니다.

예시 (node dist/bin.js … 또는 npm run persona -- …)

node dist/bin.js sample --province 서울 --age 30-39 --sex 여자 -n 5 --seed panelA
node dist/bin.js sample --match 등산 -n 3
node dist/bin.js sample --occupation 요리 -n 3 --only culinary,travel
node dist/bin.js sample --province 부산 -n 10 --format json -o panel.json

명령어

명령	설명
persona setup	데이터셋 9개 샤드 다운로드 (멱등)
persona fields	필터 가능한 컬럼·테마 목록
persona values <컬럼>	컬럼의 값과 빈도
persona stats [필터] [--by 컬럼]	세그먼트 총 건수 또는 컬럼별 분포
persona sample [필터] -n N	조건에 맞는 N명 선택 → 브리프 출력
persona get <uuid>	uuid로 단건 조회

필터 플래그 (sample/stats 공통)

• 범주형(콤마 다중값): --sex --province --district --education --marital --military --family-type --housing --bachelors-field --country
• 나이 범위: --age 30-39 · --age 65- · --age=-29(상한만, 값이 -로 시작하므로 = 사용) · --age 40
• 직업 키워드(부분일치): --occupation 회계
• 자유 텍스트: --match 등산

값은 persona values <컬럼>으로 확인하세요.

출력 포맷 (--format)

• brief(기본): 2인칭 role-play 지시문 — 서브에이전트 주입용
• profile: 3인칭 인물 프로필
• json: 26개 원본 필드(리스트 필드는 배열로 파싱)

기본 브리프는 6개 주제별 페르소나를 모두 포함하며, --only <테마,...>로 줄일 수 있습니다.

기술 스택 · 개발

• Node.js ≥ 20, TypeScript, @duckdb/node-api(DuckDB Neo, arm64 프리빌트)
• 테스트: node:test (소규모 픽스처, 2GB 불필요)

npm test     # 51개 테스트
npm run build

모듈 구조는 Python 버전과 1:1 대응: schema · query · format · data · vocab · cli.

데이터 출처 · 라이선스

NVIDIA Nemotron-Personas-Korea, CC BY 4.0. KOSIS·대법원·국민건강보험공단 등 한국 공공 통계 분포 기반의 합성 데이터입니다. 실제 개인이 아닙니다.