MiroFish — 문서 기반 GraphRAG와 OASIS 멀티에이전트 시뮬레이션으로 “미래를 리허설”하는 예측 엔진

Figure 1. MiroFish 공식 로고.

한 줄 요약

MiroFish는 PDF/Markdown/TXT 같은 seed 문서를 입력으로 받아, LLM이 도메인 온톨로지를 만들고 Zep 그래프 메모리에 GraphRAG를 구축한 뒤, 그 그래프의 엔티티를 OASIS 에이전트로 변환해 Twitter/Reddit 유사 플랫폼에서 병렬 시뮬레이션을 돌리고, 마지막에 ReportAgent가 보고서와 대화형 분석 인터페이스를 제공하는 시스템이다.

분석 메모: GitHub Wiki는 현재 별도 공개 문서가 확인되지 않아, 본 문서는 README, Discussion, 디렉터리 구조, 핵심 백엔드/프런트엔드 파일을 중심으로 재구성했다.

Quick Links

• 저장소: github.com/666ghj/MiroFish
• 공식 README: README.md
• 라이브 데모: mirofish-live-demo
• Discussions: GitHub Discussions
• 커뮤니티 허브: mirofish.ai
• 기반 엔진: CAMEL-AI OASIS
• 기반 논문: OASIS: Open Agent Social Interaction Simulations with One Million Agents
• 데모 영상 1: Wuhan University Public Opinion Simulation
• 데모 영상 2: Dream of the Red Chamber Lost Ending Simulation

프로젝트 목적과 포지셔닝

MiroFish의 README가 내세우는 핵심 문장은 “upload seed materials + describe your prediction requirements in natural language”다. 즉, 이 프로젝트는 전통적인 에이전트 시뮬레이터처럼 처음부터 world state와 agent schema를 손으로 짜게 하지 않는다. 대신 문서 업로드 → 온톨로지 생성 → 그래프 구축 → 에이전트 프로필 생성 → 병렬 시뮬레이션 → 보고서/대화라는 생산 라인을 구성한다.

이 점이 MiroFish의 가장 큰 차별점이다. 많은 멀티에이전트 프레임워크가 “agent 간 협업” 자체에 초점을 맞춘다면, MiroFish는 그보다 한 단계 위에서 현실의 seed corpus를 사회적/서사적 시뮬레이션 세계로 변환하는 파이프라인을 제공한다. README의 예시가 정책 초안, 속보, 금융 시그널뿐 아니라 소설까지 포괄하는 이유도 여기에 있다. 결국 이 프로젝트는 forecasting engine이라기보다, structured scenario rehearsal engine에 더 가깝다.

 

Figure 2. 사용자가 문서를 업로드하고 자연어로 예측 목표를 입력하는 진입점. README의 설명과 코드상 /api/graph/ontology/generate 흐름이 만나는 구간이다.

Key Features

1. 문서에서 곧바로 시뮬레이션용 온톨로지를 만든다

backend/app/api/graph.py의 generate_ontology()는 업로드된 PDF/MD/TXT를 프로젝트 디렉터리에 저장하고, FileParser로 텍스트를 추출한 뒤 OntologyGenerator에 넘겨 엔티티 타입/관계 타입을 생성한다. 흥미로운 점은 OntologyGenerator가 단순 free-form schema를 허용하지 않고, Zep 제약을 고려해 엔티티 타입 수와 엣지 타입 수를 제한하며, 엔티티 이름은 PascalCase, 관계 이름은 SCREAMING_SNAKE_CASE로 정규화한다는 점이다.

이 설계는 매우 실용적이다. 많은 “문서 → 그래프” 파이프라인이 ontology를 사람이 미리 설계해야 하는데, MiroFish는 이 고비를 LLM으로 넘기면서도 downstream 시스템 제약을 반영한다. 즉, 생성형이지만 완전히 방임적이지 않은 ontology-first 설계다.

2. GraphRAG 중심의 메모리 레이어를 세운다

GraphBuilderService는 텍스트를 chunk로 나누고, Zep graph를 생성한 뒤 ontology를 설정하고, 배치 단위로 episode를 추가한다. 이후 Zep 처리가 끝날 때까지 기다리며 graph info를 수집한다. 이 흐름 때문에 MiroFish의 그래프는 단순 시각화 산출물이 아니라, 뒤 단계에서 반복적으로 읽히는 실행 가능한 memory substrate가 된다.

이 레이어 덕분에 이후의 보고서 도구, 에이전트 인터뷰, graph statistics, entity summary, quick search 등이 모두 같은 기억 저장소를 공유한다. MiroFish가 GraphRAG를 단순 retrieval gimmick이 아니라 전체 시스템의 공통 메모리로 쓰고 있다는 뜻이다.

 

Figure 3. 그래프 패널은 MiroFish의 핵심 검증 포인트다. 생성된 노드·관계·속성을 사람이 직접 확인할 수 있어, 이후 시뮬레이션의 품질을 앞단에서 점검할 수 있다.

3. 그래프 엔티티를 OASIS 에이전트 프로필로 materialize 한다

OasisProfileGenerator는 Zep에서 노드와 주변 사실을 다시 읽어와 persona, bio, profession, interested_topics, follower_count 같은 필드를 채운다. 중요한 디테일은 이 생성기가 개인형 엔티티와 집단형 엔티티를 구분해 서로 다른 프롬프트를 사용한다는 점이다. 즉, 사람이 될 수 있는 노드와 집단/조직 성격의 노드를 동일하게 취급하지 않는다.

이 레이어는 사실상 번역기다. 문서에서 추출된 “개체”가 곧바로 시뮬레이션 가능한 “행위자”가 되는 것은 아니기 때문이다. MiroFish는 이 간극을 graph enrichment + persona synthesis로 메운다.

 

Figure 4. Step 2 환경 준비 화면. 그래프가 단순 시각화로 끝나지 않고, 실제 에이전트 집합과 시뮬레이션 파라미터로 변환되는 과정을 보여 준다.

4. Twitter/Reddit 유사 월드를 병렬로 돌린다

README는 “Dual-platform parallel simulation”을 전면에 내세우고, 실제 코드에서도 SimulationManager와 SimulationRunner가 twitter / reddit 플랫폼 타입을 동시에 다룬다. 프런트엔드 Step3Simulation.vue 역시 Info Plaza와 Topic Community라는 두 개의 플랫폼 카드를 분리해 보여 준다. 이는 하나의 사건 세계를 서로 다른 인터페이스 규칙과 상호작용 문화 위에서 동시에 관찰하려는 설계다.

이 포인트는 상당히 중요하다. 같은 사건도 타임라인 중심 플랫폼과 커뮤니티 중심 플랫폼에서 확산 구조가 달라지기 때문이다. 따라서 MiroFish는 “에이전트들이 대화한다” 수준을 넘어서, 플랫폼 affordance가 집단 역학을 어떻게 바꾸는가까지 노리는 프로젝트라고 볼 수 있다.

 

Figure 5. 이 화면은 시뮬레이션이 단순 채팅 루프가 아니라, 시간 설정·에이전트 구성·이벤트 컨텍스트를 가진 규칙 기반 실행 환경이라는 점을 보여 준다.

5. 보고서는 사후 정리물이 아니라, 도구 호출형 분석 에이전트의 산출물이다

ReportAgent는 먼저 outline을 계획하고, 그 다음 섹션별로 ReACT 스타일 반복을 돌리면서 작성한다. 내부 도구로는 insight_forge, panorama_search, quick_search, interview_agents가 보이며, /api/report는 보고서 생성, 섹션 조회, 마크다운 다운로드, agent log/console log streaming까지 제공한다.

이 조합은 꽤 인상적이다. 대부분의 멀티에이전트 프로젝트에서 리포트는 “끝난 뒤 한 번 요약하는 텍스트”에 머무르지만, MiroFish에서는 리포트 자체가 도구 사용과 자기반성(logged reasoning loop)을 통해 생성되는 분석 객체다. 즉, 이 프로젝트의 리포트는 그냥 결과물이 아니라, post-simulation analytics interface의 일부다.

Figure 6. 보고서 생성 화면. 생성된 본문뿐 아니라 계획, 진행률, 로그가 함께 보여서 LLM 보고서 생성 과정을 어느 정도 감사할 수 있다.

6. 보고서 이후에도 세계와 대화할 수 있다

Step5Interaction.vue는 ReportAgent와의 대화, 개별 에이전트와의 대화, 설문 전송 UI를 함께 제공한다. ReportAgent 도구 카드에는 InsightForge, PanoramaSearch, QuickSearch, InterviewSubAgent가 노출되어 있고, 사용자는 특정 agent를 골라 직접 대화할 수도 있다.

여기서 MiroFish의 성격이 명확해진다. 이 프로젝트는 “한 번 돌리고 PDF 받는 서비스”가 아니다. 오히려 시뮬레이션된 세계를 탐사하는 workbench에 가깝다. 보고서는 종착점이 아니라, 더 깊은 질의를 시작하는 인덱스다.

 

Figure 7. Deep Interaction 단계. MiroFish가 단순 보고서 생성기보다 ‘탐색형 시뮬레이션 워크벤치’에 가깝다는 점이 가장 잘 드러나는 화면이다.

7. 다국어 UI와 단계형 워크플로가 분리되어 있다

frontend/src/i18n/index.js는 /locales/*.json을 동적으로 불러오며, 저장된 locale을 localStorage에 유지한다. 또한 router/index.js는 Process → Simulation → Start → Report → Interaction의 route를 분리해 둔다. 이것은 거대한 단일 페이지보다 5단계 생산 라인형 UX를 지향한다는 뜻이다.

사용자 경험 측면에서 보면, MiroFish는 “agent playground”보다 “simulation studio”에 더 가깝다. 단계별 스테이지가 분리되어 있기 때문에, 각 단계의 실패와 중간 산출물을 비교적 잘 관찰할 수 있다.

Tech Stack

영역	기술
Backend	Python 3.11–3.12, Flask >=3.0, flask-cors >=6.0, OpenAI-compatible SDK, PyMuPDF >=1.24, python-dotenv, pydantic
Graph / Memory	Zep Cloud 3.13.0
Multi-agent Simulation	CAMEL-AI ecosystem, camel-ai 0.2.78, camel-oasis 0.2.5
Frontend	Vue 3.5.24, Vue Router 4.6.3, Vue I18n 11.3.0, Axios 1.14.0, D3 7.9.0, Vite 7.2.4
Tooling	Node.js 18+, npm, uv, Docker, docker-compose, concurrently 9.1.2
License	AGPL-3.0

코드베이스 해부

backend/
  app/
    api/        Flask route layer (`graph.py`, `simulation.py`, `report.py`)
    services/   ontology/graph/profile/simulation/report orchestration
    models/     project/task persistence
    utils/      file parser, LLM client, locale, retry, logging
frontend/
  src/
    components/ step panels + GraphPanel
    views/      route-level workflow pages
    api/        axios wrappers for graph/simulation/report
locales/        en/zh translation bundles
static/image/   screenshots, logo, demo covers

이 구조에서 가장 인상적인 부분은 services/ 디렉터리가 곧 시스템 설계도를 대체한다는 점이다. ontology_generator.py, graph_builder.py, oasis_profile_generator.py, simulation_config_generator.py, simulation_manager.py, simulation_runner.py, report_agent.py가 거의 그대로 파이프라인의 주요 노드가 된다. 즉, 아키텍처가 서비스 파일명에 비교적 정직하게 드러나 있다.

Architecture

Figure 8. README, 디렉터리 구조, 핵심 서비스 파일을 바탕으로 재구성한 MiroFish 아키텍처. 저장소에 공식 아키텍처 그림이 없어 분석용으로 다시 그렸다.

1) Ingestion & Project Context

사용자는 seed 문서와 simulation requirement를 업로드한다. ProjectManager가 프로젝트 단위 컨텍스트를 만들고, FileParser가 PDF/MD/TXT를 텍스트로 변환한다. 이 구조 덕분에 업로드 파일, 추출 텍스트, ontology, graph ID, report ID가 한 프로젝트 흐름에 묶인다. 실서비스 관점에서는 이것이 매우 중요하다. 그래프와 시뮬레이션이 stateless utility가 아니라, 추적 가능한 프로젝트 개체가 되기 때문이다.

2) Ontology-first Graph Pipeline

MiroFish는 먼저 ontology를 생성한 뒤 그래프를 만든다. 이 방식의 장점은 이후 검색, 에이전트 프로필 생성, 보고서 도구가 같은 schema를 공유한다는 점이다. 반대로 단점도 분명하다. ontology 품질이 낮으면 뒤 단계 전체가 연쇄적으로 흔들릴 수 있다. 따라서 이 구조는 “빠른 일반화”와 “연쇄 오류 가능성”을 동시에 안고 있다.

3) Agent Materialization Layer

ZepEntityReader가 그래프 엔티티를 읽고, OasisProfileGenerator가 에이전트 프로필을 구성한다. 이어 SimulationConfigGenerator가 총 시뮬레이션 시간, 라운드 길이, 활성 시간대, 에이전트별 행동 구성, 플랫폼별 설정을 생성한다. 결과적으로 “문서 속 개체”가 “행동하는 agent population”으로 변환된다. 이때 persona generation과 platform config generation이 분리되어 있어, 사람 설정과 세계 설정을 별도로 제어할 수 있다.

4) Dual-world Execution Layer

SimulationManager는 시뮬레이션 상태 파일을 보존하고, SimulationRunner는 백그라운드에서 라운드를 실행한다. 실행 도중 생성된 posts/comments/actions는 실시간 상태와 함께 누적된다. 특히 ZepGraphMemoryUpdater가 개별 행동과 기억 변화를 다시 그래프/메모리 레이어와 연결한다는 점이 핵심이다. 이 덕분에 시뮬레이션 결과와 지식 그래프가 완전히 분리되지 않는다. 다시 말해, MiroFish는 정적 knowledge graph + 동적 social simulation을 순환시킨다.

5) Report & Interactive Reasoning Layer

ReportAgent는 시뮬레이션 결과를 읽고 outline → section generation → reflection 순서로 보고서를 만든다. 이후 동일한 리포트 컨텍스트에서 도구 호출형 대화를 수행한다. 이런 구조는 “생성 한 번으로 끝나는 보고서”가 아니라, 생성 후 질의 가능한 분석 객체를 만든다. 이는 멀티에이전트 시스템을 프로덕트화할 때 매우 유리한 패턴이다.

6) Frontend Workbench Layer

GraphPanel.vue는 D3 force graph 기반의 검증 인터페이스다. Step 컴포넌트는 파이프라인 단계별 조작을 노출하고, route-level view는 프로젝트/시뮬레이션/보고서 ID를 기준으로 상태를 이어받는다. 전체적으로 백엔드가 생산 라인이라면, 프런트엔드는 그 생산 라인의 관제실에 가깝다. 복잡한 시뮬레이터일수록 이런 “중간 상태를 보는 창”이 중요하다.

Usage & Setup

권장 실행 환경

• Node.js 18+
• Python 3.11–3.12
• uv 최신 버전

필수 환경 변수

cp .env.example .env

LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
ZEP_API_KEY=your_zep_api_key

README는 OpenAI SDK 형식의 LLM API를 지원한다고 설명하며, 예시로 DashScope의 Qwen-plus를 제시한다. 즉, OpenAI-compatible endpoint만 맞으면 모델 백엔드는 교체 가능하다.

설치

npm run setup:all

분리 설치도 가능하다.

npm run setup
npm run setup:backend

실행

npm run dev

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001

개별 실행도 가능하다.

npm run backend
npm run frontend

Docker

docker compose up -d

실제 사용 흐름 요약

1. 문서를 업로드하고 자연어로 “무엇을 예측할지”를 적는다.
2. ontology와 graph를 생성한다.
3. simulation environment를 준비하고 agent profiles/config를 확인한다.
4. 시뮬레이션을 실행하고 report를 생성한다.
5. ReportAgent 또는 개별 agent와 대화한다.

Figure 9. 설치 이후 사용자가 가장 먼저 보게 되는 진입 화면. MiroFish는 복잡한 ABM 설정 화면보다 문서 업로드 UX를 전면에 세운다.

Personal Insights

의료 AI 관점

MiroFish는 “정책/이슈/사건이 사람들의 반응을 거쳐 어떻게 사회적으로 전개될지”를 리허설하는 데 강하다. 그래서 병원 운영 시나리오, 보건 정책 커뮤니케이션, 백신/감염병 관련 여론 시뮬레이션처럼 사람 간 상호작용과 정보 확산이 중요한 문제에 특히 잘 맞는다. 반면, 현재 구조는 사회 시뮬레이션에 최적화되어 있어서 임상 의사결정 지원처럼 정량적 정확도, 불확실성 보정, 근거 추적, 개인정보 통제가 핵심인 의료 AI에는 바로 투입하기 어렵다.

의료 도메인으로 확장하려면 최소한 네 가지가 더 필요하다. 첫째, SNOMED CT/LOINC 같은 표준 ontology 연결. 둘째, PHI/PII 제거 및 접근통제. 셋째, simulation outcome의 calibration 및 retrospective evaluation. 넷째, 전문가 승인 절차와 audit trail 강화다. 요약하면, MiroFish는 의료 AI의 “사회적/운영적 시뮬레이션 레이어”로는 흥미롭지만, “증거급 임상 추론 엔진”으로 보기에는 아직 거리가 있다.

Bioinformatics 관점

문헌·리포트·노트에서 엔티티와 관계를 뽑아 그래프로 만들고, 이후 질의/요약/리포트로 연결하는 앞단 파이프라인은 bioinformatics에도 매우 매력적이다. 예를 들어 gene–protein–pathway–disease–drug 관계를 seed corpus에서 구축하고 탐색하는 용도로는 구조가 잘 맞는다. FileParser → OntologyGenerator → GraphBuilderService → ReportAgent 흐름만 떼어 써도 literature intelligence 시스템으로 쓸 수 있다.

하지만 MiroFish의 시뮬레이션 엔진은 본질적으로 “social agents on platforms”에 맞춰져 있다. 따라서 bioinformatics에 옮기려면 에이전트 semantics를 크게 바꿔야 한다. 세포, 단백질, 실험군, 연구자, 논문을 동일한 social persona 프레임으로 다루는 것은 자연스럽지 않기 때문이다. 즉, 현재 형태는 생물학 지식 그래프를 탐색하는 프런트엔드로는 유망하지만, 분자 메커니즘 자체를 시뮬레이션하는 플랫폼으로 보기에는 아직 결이 다르다.

Autonomous Agent 관점

이 저장소의 가장 좋은 점은 단계가 분명하다는 것이다. ontology 생성, graph build, profile generation, config generation, simulation, report, deep interaction이 서비스/컴포넌트 수준에서 비교적 명확히 분리되어 있다. 이런 구조는 디버깅, 관찰 가능성, 중간 산출물 재사용에 유리하다. 특히 agent_log, console_log, graph panel, section-based report generation은 “에이전트 시스템이 무엇을 했는지”를 추적하기 쉽게 만든다.

약점도 분명하다. 각 단계가 LLM 출력에 기대기 때문에 upstream hallucination이나 schema drift가 downstream 전체를 오염시킬 수 있고, 비용·지연시간·재현성 문제가 누적되기 쉽다. 또한 프로젝트 README와 코드에서는 비전과 제품 경험이 잘 드러나지만, 엄격한 benchmark와 evaluation 프로토콜은 아직 전면에 보이지 않는다. 그럼에도 MiroFish는 단일 거대 에이전트보다 inspectable multi-stage agent pipeline이라는 점에서 오픈소스 설계가 꽤 좋다.

종합 평가

MiroFish의 현재 최적 사용처는 “정확한 수치 예측기”라기보다, 사건·이슈·서사의 가능 세계를 병렬로 탐색하는 전략적 시뮬레이션 워크벤치다. 특히 public opinion rehearsal, social scenario planning, narrative branching, speculative policy testing 같은 분야에서 잠재력이 크다. 반대로 benchmarked forecasting engine이나 high-assurance domain expert system으로 쓰려면, 검증 레이어와 정량 평가 체계가 더 필요하다.

Sources Consulted

• README: README.md
• Discussions: GitHub Discussions
• 백엔드 핵심 파일:
  • backend/app/api/graph.py
  • backend/app/api/simulation.py
  • backend/app/api/report.py
  • backend/app/services/ontology_generator.py
  • backend/app/services/graph_builder.py
  • backend/app/services/oasis_profile_generator.py
  • backend/app/services/simulation_config_generator.py
  • backend/app/services/simulation_manager.py
  • backend/app/services/simulation_runner.py
  • backend/app/services/report_agent.py
  • backend/app/utils/file_parser.py
  • backend/app/config.py
• 프런트엔드 핵심 파일:
  • frontend/src/components/GraphPanel.vue
  • frontend/src/components/Step1GraphBuild.vue
  • frontend/src/components/Step2EnvSetup.vue
  • frontend/src/components/Step3Simulation.vue
  • frontend/src/components/Step4Report.vue
  • frontend/src/components/Step5Interaction.vue
  • frontend/src/views/MainView.vue
  • frontend/src/views/SimulationView.vue
  • frontend/src/views/ReportView.vue
  • frontend/src/views/InteractionView.vue
  • frontend/src/router/index.js
  • frontend/src/i18n/index.js
• 의존성 및 실행 설정:
  • package.json
  • frontend/package.json
  • backend/pyproject.toml
  • .env.example