🤖 AgentCourt-LangGraph: AI 에이전트 기반 모의 법정 시뮬레이션

본 프로젝트는 LangGraph를 기반으로 LLM(거대 언어 모델) 에이전트들이 상호작용하여 실제 법정의 재판 과정을 시뮬레이션하는 시스템입니다. AgentCourt와 AgentsBench 논문에서 영감을 받아, 변호사, 판사, 재판장 등 각자의 역할을 가진 AI 에이전트들이 유기적인 재판 절차를 통해 판결을 내리고, 그 결과를 바탕으로 스스로 학습하며 진화합니다.

🎯 프로젝트 목표

• 동적 재판 시뮬레이션: 정해진 각본이 아닌, 여러 AI 에이전트들의 실시간 상호작용을 통해 매번 다른 재판 과정을 생성합니다.
• 에이전트의 진화: 변호사 에이전트가 재판의 승패 경험을 데이터베이스에 축적하고, 이를 다음 변론에 활용하는 '적대적 학습' 루프를 구현합니다.
• 객관적 성능 평가: 생성된 판결을 '논리적 일관성', '법률적 타당성', '사회적 가치' 기준으로 자동 평가하여 시스템의 성능을 벤치마킹합니다.

🏛️ 핵심 아키텍처

본 시스템은 LangGraph를 통해 다음과 같은 순서로 제어되는 상태 머신(State Machine)으로 동작합니다.

[시작: 사건 접수] -> [토론: 변호사 공방] -> [심의: 서브 판사 의견] -> [판결: 재판장 선고] -> [학습: DB 업데이트] -> [평가: 벤치마크 점수] -> [종료]

✨ 주요 기능

• 다중 에이전트 시스템: LangGraph를 기반으로 변호사, 판사, 재판장, 평가자 등 여러 AI 에이전트가 순차적으로 상호작용합니다.
• 적대적 학습 및 진화: 변호사 에이전트는 매 재판의 승패 결과를 '교훈'으로 삼아 개인 DB(Redis)에 저장하고, 다음 재판에서 이를 활용하여 점차 진화합니다.
• 영구적 사건 아카이브: 모든 재판 기록과 벤치마크 점수는 PostgreSQL 벡터 데이터베이스에 영구적으로 저장되어, 유사 사건 검색 등에 활용될 수 있습니다.
• 동적 판사 구성: 매 재판마다 각기 다른 성향의 서브 판사들이 무작위로 배정되어 재판 결과의 다양성을 높입니다.
• 자동 벤치마킹: AgentsBench 논문의 평가 방식을 따라, 매 재판마다 생성된 판결의 품질을 논리성, 타당성, 사회적 가치 측면에서 자동으로 평가합니다.

⚙️ 실행 환경 설정

1. 사전 준비

• Docker가 설치되어 있어야 합니다.
• Python 3.9 이상의 환경이 필요합니다.

2. 프로젝트 설정

# 1. 이 레포지토리를 클론합니다.
git clone [레포지토리 주소]
cd [레포지토리 폴더]

# 2. API 키를 설정합니다.
# .env.example 파일을 복사하여 .env 파일을 만듭니다.
cp .env.example .env

# 3. .env 파일을 열어 사용할 LLM 공급자에 맞게 환경 변수를 설정합니다.
#    - 기본값은 OpenAI이므로 `OPENAI_API_KEY`(필수)와 `OPENAI_MODEL`(선택)을 채웁니다.
#    - NVIDIA NIM을 사용하려면 `LLM_PROVIDER=nvidia`, `NVIDIA_API_KEY`를 지정하고
#      필요 시 `NVIDIA_NIM_MODEL`, `NVIDIA_NIM_BASE_URL`을 설정합니다.
# (선택) LangSmith 추적을 원하면 해당 부분의 주석을 해제하고 정보를 입력합니다.

# 4. 필요한 파이썬 라이브러리를 설치합니다.
pip install -r requirements.txt

# 5. Docker로 데이터베이스(Redis, PostgreSQL)를 실행합니다.
docker-compose up -d

Docker 컨테이너가 정상적으로 실행되었는지 docker ps 명령어로 확인합니다.

🚀 사용 방법

1. (선택사항) 데이터셋으로 사전 학습시키기

변호사 에이전트들이 똑똑한 상태에서 시작하게 하려면, batch_learn.py를 실행하여 제공된 데이터셋(train.jsonl)으로 사전 학습을 진행할 수 있습니다.

# 이 과정은 데이터셋 크기에 따라 많은 API 호출과 시간이 소요될 수 있습니다.
python batch_learn.py

2. 단일 모의 법정 실행하기

main.py를 실행하면, 하나의 가상 사건에 대한 전체 재판 시뮬레이션 과정을 터미널에서 실시간으로 확인할 수 있습니다.

python main.py

3. 벤치마크 테스트 실행하기

benchmark.py를 사용하여 '학습 전'과 '학습 후'의 성능을 객관적인 점수로 비교할 수 있습니다.

학습 전 성능 측정 (DB 초기화 후 진행):

python benchmark.py --mode untrained

학습 후 성능 측정 (DB 데이터 유지):

python benchmark.py --mode trained

테스트가 끝나면, 결과는 터미널과 benchmark_results_... .csv 파일로 저장됩니다. CSV에는 각 사건의 정답 라벨(expected_outcome), 모델 판결(model_outcome), 일치 여부(is_correct), 세 가지 품질 기준별 점수와 사유가 함께 기록됩니다. 실행이 끝나면 정확도, Macro F1, 원고 승소율 등의 정량 지표가 요약 표로 출력됩니다.

ℹ️ data/test.jsonl에는 각 사건의 예상 판결 결과를 나타내는 expected_outcome 필드가 포함되어야 하며, 값은 승리, 패배, 무승부 중 하나여야 합니다.

🗃️ 데이터베이스 관리

• 데이터 확인: DBeaver나 pgAdmin과 같은 툴을 사용하여 localhost:5433 (PostgreSQL) 또는 localhost:6379 (Redis)에 접속하면 저장된 데이터를 직접 확인할 수 있습니다.
• 데이터 완전 초기화: 모든 학습 내용을 지우고 처음부터 다시 시작하고 싶다면, 아래 명령어를 사용하세요.

  docker-compose down -v