[ GTRPGM ] — [ AI 게임 마스터 시스템 ]

"서사·상태 일관성을 보장하는 AI 게임 마스터 시스템 — PostgreSQL + Apache AGE 이중 저장소 설계, FastAPI 기반 마이크로서비스 아키텍처, NVIDIA AI Academy 최우수상 수상”

기간/형태: [2026.01] ~ [2026.02] / [팀(4인) 작업]
개발환경: Linux (WSL2 / Ubuntu) / No GPU / Python 3.11 / VSCode
시연영상: https://youtu.be/QjXMNFUAJ1Q
링크: 팀 레포 [‣] || 담당 레포 [ ‣] || 작업로그_https://lyeum.tistory.com/category/%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8/TRPG | https://github.com/GTRPGM/main/issues?q=is%3Aissue state%3Aclosed

1) 목표: 서사 일관성과 상태 일관성을 보장할 수 있는 AI 게임 마스터를 만들자

개발의 시작점 기존의 TRPG를 제공하는 챗봇들의 품질적인 한계로 몰입에 아쉬운 경우가 많았기에, 이를 극복하고자, 그리고 더 TRPG에 충실하고자 개발을 진행하게 되었습니다.
기술스택

구분	기술
Runtime	Python 3.11+
Framework	FastAPI + Uvicorn
DB (관계형)	PostgreSQL + asyncpg
DB (그래프)	Apache AGE (Cypher)
Validation	Pydantic v2
AI Integration	LangGraph, LangChain Core
Test	pytest-asyncio, testcontainers
Package Manager	uv

2) 담당 역할: State Manager

: State Manager는 GTRPGM(Generative TRPG Manager) 엔진의 중앙 상태 저장소 서비스입니다. 게임 내에서 일어나는 모든 변화—플레이어의 HP 감소, NPC와의 호감도 변화, 아이템 획득, 장소 이동—를 일관성 있게 저장하고 제공하는 역할을 담당했습니다.

주요 업무
[ ] State DB 구축
[ ] 상태 DB와 외부 DB 간의 schema 계약
[ ] 상태 정보의 파이프라인 작성

3) 아키텍쳐/구현 요약

전체 시스템 아키텍쳐

전체 서비스의 관계를 보면 알 수 있듯, 제가 이 서비스를 설계할 때 가장 먼저 정한 원칙은 판정(Judgment)과 상태(State)의 분리였습니다.

TRPG에서 주사위를 굴리고 대미지를 계산하는 행위는 게임 규칙에 대한 판단이고, 그 결과를 기록하는 행위는 상태 관리입니다. 이 두 가지를 하나의 서비스가 모두 책임지면 규칙이 바뀔 때마다 상태 저장 로직까지 함께 수정해야 하는 문제가 생깁니다.

때문에 State Manager는 Rule Engine이 계산한 결과를 수동적으로 받아 저장하는 데만 집중합니다. 무엇을 어떻게 계산할지는 알지 못하고, 알 필요도 없습니다. 이 분리 덕분에 게임 규칙이 바뀌어도 State Manager는 변경이 필요 없으며, 반대로 상태 저장 방식이 바뀌어도 Rule Engine은 영향을 받지 않습니다.

State Manager

State Manager 아키텍쳐
State DB( ApacheAGE + PostgreSQL )

4) 진행중 발생한 트러블 이슈

주요 버그사항

5) 결과

설계 단계에서 정한 판정과 상태의 분리 원칙이 실제로 유효했음을 프로젝트 후반에 직접 확인했습니다. Rule Engine 쪽 게임 규칙이 변경됐을 때 State Manager 코드는 한 줄도 수정하지 않았고, 반대로 상태 저장 방식이 바뀌었을 때도 Rule Engine은 영향을 받지 않았습니다. 마스터 세션(Session 0) 딥 카피 구조 덕분에 세션 간 데이터 간섭이 발생하지 않았고, DB 트리거 기반 자동 동기화로 두 DB 간 불일치 문제를 애플리케이션 레벨에서 신경 쓸 필요가 없었습니다. 프로젝트 완성도를 인정받아 최우수상을 수상했습니다.