MiroFish의 아이디어를 작게 재구성하여 로컬에서 돌려볼 수 있는 시뮬레이터입니다. 뉴스 URL, 텍스트, Markdown 파일을 입력하면 LM Studio 로컬 LLM을 사용해 지식 그래프, 에이전트 프로필, 라운드별 사회 시뮬레이션, Markdown 리포트를 생성합니다.

원본 프로젝트: 666ghj/MiroFish

Preview

그래프와 에이전트 프로필

라운드별 대화 시뮬레이션

Markdown 리포트

주요 기능

• URL 기반 뉴스 수집: trafilatura로 HTML을 가져오고 LLM이 기사 제목/본문을 정리
• 텍스트/파일 입력: 직접 붙여넣기 또는 TXT/MD 업로드 지원
• 지식 그래프: D3 기반 인터랙티브 노드/링크 그래프
• 에이전트 프로필: 추출된 엔티티를 기반으로 입장과 행동 생성
• 라운드별 시뮬레이션: 라운드가 끝날 때마다 UI에 대화 로그 표시
• 리포트: 시뮬레이션 로그 기반 한국어 Markdown 리포트
• 로컬 저장: SQLite DB와 data/uploads/url Markdown 파일 사용

기술 스택

영역	사용 기술
Backend	FastAPI, SQLite, Pydantic, LM Studio API
Frontend	React, Vite, TypeScript, D3
LLM	LM Studio OpenAI-compatible API
News Fetch	trafilatura

요구 사항

• Python 3.12.1
• Node.js 20 이상 권장
• LM Studio
• 로컬 LLM 모델

설치

Windows PowerShell 기준:

pyenv local 3.12.1
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm install
npm --prefix frontend install

새 가상환경을 직접 만들 경우:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

환경 설정

루트에 .env 파일을 둡니다. 예시는 .env.example을 참고하세요.

MINI_MIROFISH_LM_STUDIO_BASE_URL=http://localhost:1234/v1
MINI_MIROFISH_LM_STUDIO_MODEL=your-loaded-model-id
MINI_MIROFISH_LLM_MAX_TOKENS=8192
MINI_MIROFISH_LLM_DISABLE_THINKING=true

.env는 Git에 포함하지 않습니다.

LM Studio 준비

1. LM Studio에서 모델을 로드합니다.
2. Local Server를 켭니다.
3. /v1/models에 모델 id가 보이는지 확인합니다.

http://localhost:1234/v1/models

백엔드 health에서 사용하는 모델도 확인할 수 있습니다.

http://127.0.0.1:8011/health

실행

백엔드:

.\scripts\run_backend.ps1

프론트엔드:

npm --prefix frontend run dev

동시 실행:

npm run dev

접속 주소:

http://127.0.0.1:5173

API 문서:

http://127.0.0.1:8011/docs

사용 흐름

1. Text, File, URL 중 하나를 선택합니다.
2. 시뮬레이션 Topic, Rounds, Agents를 입력합니다.
3. Run Full Pipeline을 실행합니다.
4. All, Knowledge Graph, Agent Profiles, Simulation, Report 탭에서 결과를 확인합니다.

개별 단계만 실행할 수도 있습니다.

Register -> Graph -> Agents -> Simulate -> Report

파이프라인 동작 원리

주요 API

• GET /health
• GET /documents
• POST /documents
• POST /documents/from-url
• POST /documents/upload
• DELETE /documents/{document_id}
• POST /documents/{document_id}/extract-graph
• POST /documents/{document_id}/agents/generate
• POST /documents/{document_id}/simulate/round
• POST /documents/{document_id}/simulate
• POST /documents/{document_id}/report
• POST /pipeline

데이터 저장

• SQLite DB: data/graph.db
• URL 정리 Markdown: data/uploads/url
• 업로드 파일: data/uploads

히스토리 삭제 시 관련 DB 데이터와 매칭되는 업로드 파일이 함께 삭제됩니다.

LM Studio 모델 주의사항

Qwen3.5 9B를 LM Studio에서 사용할 때 아래 문제가 발생할 수 있습니다.

• reasoning_content가 매우 길게 생성되고 정작 content가 비어 있거나 잘리는 경우가 있습니다.
• finish_reason: "length"로 끝나면서 JSON 본문이 완성되지 않아 LLM 응답을 JSON object로 파싱할 수 없습니다 오류가 발생할 수 있습니다.
• response_format: {"type": "json_object"} 요청에서 일부 LM Studio/모델 조합이 400 Bad Request를 반환할 수 있습니다.
• 그래프 추출 결과의 target이 엔티티 목록에 없는 값으로 생성되면 D3에서 node not found 오류가 날 수 있습니다.
• 영문 인명이나 고유명사가 한국어/한자식 표기로 변형되어 같은 인물이 중복 노드처럼 보일 수 있습니다.

이 프로젝트는 위 문제를 줄이기 위해 .env의 MINI_MIROFISH_LLM_DISABLE_THINKING=true, JSON 복구 로직, 고유명사 보존 규칙, 누락 노드 방어 처리를 포함합니다. 그래도 모델별 출력 안정성 차이가 있으므로, LM Studio에서 실제 로드한 모델 id를 .env의 MINI_MIROFISH_LM_STUDIO_MODEL에 맞춰 주세요.

한계

• 뉴스 사이트가 봇 차단 또는 강한 JavaScript 렌더링을 사용하면 URL 추출이 실패할 수 있습니다.
• 로컬 LLM의 JSON 출력 품질에 따라 그래프 품질이 달라질 수 있습니다.
• SQLite 기반 MVP라 실제 temporal knowledge graph 저장소는 아닙니다.
• 에이전트 시뮬레이션은 연구용 멀티에이전트 환경이 아니라 간단한 라운드 루프입니다.