Merge upstream PR 666ghj#374: pluggable graph backends (Zep Cloud + Graphiti local)

Author: blks

.env.example

@@ -1,34 +1,45 @@
-# =============================================================================
-# Copy to .env and fill in real values. Never commit .env.
-# =============================================================================
-#
-# LLM — OpenAI-compatible HTTP API (used by backend OpenAI SDK).
-#
-# --- Option A: Hosted (e.g. Alibaba DashScope) ---
+# LLM API configuration (supports any LLM API compatible with the OpenAI SDK format)
+# Recommended: use the qwen-plus model on Alibaba Bailian: https://bailian.console.aliyun.com/
+# Note: usage can be expensive, so try simulations with fewer than 40 rounds first
 LLM_API_KEY=your_api_key_here
-LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-LLM_MODEL_NAME=qwen-plus
-#
-# --- Option B: Local Ollama (open-weight models on your machine) ---
-# 1) Install: https://ollama.com  or  brew install ollama
-# 2) Run the Ollama app (or `ollama serve`). Check: curl http://127.0.0.1:11434/api/tags
-# 3) Pull a model (pick one; larger = better quality, more RAM/GPU):
-#       ollama pull qwen2.5:7b
-#       ollama pull llama3.2:3b
-# 4) In .env, set (use the same name as `ollama list` shows):
-#       LLM_API_KEY=ollama
-#       LLM_BASE_URL=http://127.0.0.1:11434/v1
-#       LLM_MODEL_NAME=qwen2.5:7b
-# Note: MiroFish needs a non-empty LLM_API_KEY; Ollama does not validate it.
-# Note: Some flows use JSON mode; very small models may return invalid JSON.
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL_NAME=gpt-4o
 
-# ===== ZEP 记忆图谱（必填；与 LLM 无关）=====
-# 注册后在控制台创建 API Key：https://app.getzep.com/
-# 无法用本地 Hugging Face 模型替代；这是独立的云服务。
+# ===== Graph backend selection =====
+# Use zep_cloud for hosted Zep, or graphiti_local for local Neo4j + Graphiti
+GRAPH_BACKEND=zep_cloud
+
+# ===== Zep Cloud configuration =====
+# Required only when GRAPH_BACKEND=zep_cloud
 ZEP_API_KEY=your_zep_api_key_here
 
-# ===== 加速 LLM（可选；仅部分脚本使用）=====
-# 若不用，不要在 .env 中出现这些变量。
-# LLM_BOOST_API_KEY=your_api_key_here
-# LLM_BOOST_BASE_URL=your_base_url_here
-# LLM_BOOST_MODEL_NAME=your_model_name_here
+# ===== Local Graphiti + Neo4j configuration =====
+# Required only when GRAPH_BACKEND=graphiti_local
+# Note: the local Graphiti backend stores all graphs in one Neo4j database
+# and isolates each MiroFish graph by Graphiti `group_id`.
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your_neo4j_password_here
+NEO4J_DATABASE=neo4j
+GRAPHITI_AUTO_INIT=true
+GRAPHITI_TELEMETRY_ENABLED=false
+GRAPHITI_MAX_COROUTINES=10
+GRAPHITI_SEARCH_RERANKER=rrf
+
+# Optional: override Graphiti model settings
+# If omitted, Graphiti falls back to the main LLM settings above
+GRAPHITI_LLM_API_KEY=
+GRAPHITI_LLM_BASE_URL=
+GRAPHITI_LLM_MODEL=
+GRAPHITI_EMBEDDER_API_KEY=
+GRAPHITI_EMBEDDER_BASE_URL=
+GRAPHITI_EMBEDDER_MODEL=text-embedding-3-small
+GRAPHITI_RERANKER_API_KEY=
+GRAPHITI_RERANKER_BASE_URL=
+GRAPHITI_RERANKER_MODEL=
+
+# ===== Accelerated LLM configuration (optional) =====
+# If you are not using accelerated configuration, do not include the fields below in your env file
+LLM_BOOST_API_KEY=your_api_key_here
+LLM_BOOST_BASE_URL=your_base_url_here
+LLM_BOOST_MODEL_NAME=your_model_name_here

Dockerfile

@@ -1,29 +1,30 @@
 FROM python:3.11
 
-# 安装 Node.js （满足 >=18）及必要工具
+# Install Node.js (version 18 or later) and required tools
 RUN apt-get update \
   && apt-get install -y --no-install-recommends nodejs npm \
   && rm -rf /var/lib/apt/lists/*
 
-# 从 uv 官方镜像复制 uv
+# Copy `uv` from the official uv image
 COPY --from=ghcr.io/astral-sh/uv:0.9.26 /uv /uvx /bin/
 
 WORKDIR /app
 
-# 先复制依赖描述文件以利用缓存
+# Copy dependency manifests first to take advantage of layer caching
 COPY package.json package-lock.json ./
 COPY frontend/package.json frontend/package-lock.json ./frontend/
 COPY backend/pyproject.toml backend/uv.lock ./backend/
 
-# 安装依赖（Node + Python）
+# Install dependencies (Node + Python)
 RUN npm ci \
   && npm ci --prefix frontend \
-  && cd backend && uv sync --frozen
+  && cd backend && uv sync --frozen \
+  && uv pip install --python .venv/bin/python --no-deps graphiti-core==0.28.2
 
-# 复制项目源码
+# Copy the project source
 COPY . .
 
 EXPOSE 3000 5001
 
-# 同时启动前后端（开发模式）
-CMD ["npm", "run", "dev"]
+# Start both frontend and backend services (development mode)
+CMD ["npm", "run", "dev"]

README-EN.md

@@ -4,7 +4,7 @@
 
 <a href="https://trendshift.io/repositories/16144" target="_blank"><img src="https://trendshift.io/api/badge/repositories/16144" alt="666ghj%2FMiroFish | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
-简洁通用的群体智能引擎，预测万物
+A simple, universal swarm intelligence engine for predicting anything
 </br>
 <em>A Simple and Universal Swarm Intelligence Engine, Predicting Anything</em>
 
@@ -20,7 +20,7 @@
 [![X](https://img.shields.io/badge/X-Follow-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/mirofish_ai)
 [![Instagram](https://img.shields.io/badge/Instagram-Follow-E4405F?style=flat-square&logo=instagram&logoColor=white)](https://www.instagram.com/mirofish_ai/)
 
-[English](./README-EN.md) | [中文文档](./README.md)
+[README](./README.md) | [English Copy](./README-EN.md)
 
 </div>
 
@@ -49,16 +49,16 @@ Welcome to visit our online demo environment and experience a prediction simulat
 <div align="center">
 <table>
 <tr>
-<td><img src="./static/image/Screenshot/运行截图1.png" alt="Screenshot 1" width="100%"/></td>
-<td><img src="./static/image/Screenshot/运行截图2.png" alt="Screenshot 2" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-1.png" alt="Screenshot 1" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-2.png" alt="Screenshot 2" width="100%"/></td>
 </tr>
 <tr>
-<td><img src="./static/image/Screenshot/运行截图3.png" alt="Screenshot 3" width="100%"/></td>
-<td><img src="./static/image/Screenshot/运行截图4.png" alt="Screenshot 4" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-3.png" alt="Screenshot 3" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-4.png" alt="Screenshot 4" width="100%"/></td>
 </tr>
 <tr>
-<td><img src="./static/image/Screenshot/运行截图5.png" alt="Screenshot 5" width="100%"/></td>
-<td><img src="./static/image/Screenshot/运行截图6.png" alt="Screenshot 6" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-5.png" alt="Screenshot 5" width="100%"/></td>
+<td><img src="./static/image/Screenshot/screenshot-6.png" alt="Screenshot 6" width="100%"/></td>
 </tr>
 </table>
 </div>
@@ -68,15 +68,15 @@ Welcome to visit our online demo environment and experience a prediction simulat
 ### 1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction
 
 <div align="center">
-<a href="https://www.bilibili.com/video/BV1VYBsBHEMY/" target="_blank"><img src="./static/image/武大模拟演示封面.png" alt="MiroFish Demo Video" width="75%"/></a>
+<a href="https://www.bilibili.com/video/BV1VYBsBHEMY/" target="_blank"><img src="./static/image/wuhan-demo-cover.png" alt="MiroFish Demo Video" width="75%"/></a>
 
 Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"
 </div>
 
 ### 2. Dream of the Red Chamber Lost Ending Simulation
 
 <div align="center">
-<a href="https://www.bilibili.com/video/BV1cPk3BBExq" target="_blank"><img src="./static/image/红楼梦模拟推演封面.jpg" alt="MiroFish Demo Video" width="75%"/></a>
+<a href="https://www.bilibili.com/video/BV1cPk3BBExq" target="_blank"><img src="./static/image/dream-of-red-chamber-cover.jpg" alt="MiroFish Demo Video" width="75%"/></a>
 
 Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"
 </div>
@@ -122,9 +122,21 @@ LLM_API_KEY=your_api_key
 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 LLM_MODEL_NAME=qwen-plus
 
-# Zep Cloud Configuration
-# Free monthly quota is sufficient for simple usage: https://app.getzep.com/
+# Graph backend selection
+# Use zep_cloud for hosted Zep, or graphiti_local for local Neo4j + Graphiti
+GRAPH_BACKEND=zep_cloud
+
+# Zep Cloud configuration
+# Required only when GRAPH_BACKEND=zep_cloud
 ZEP_API_KEY=your_zep_api_key
+
+# Local Graphiti + Neo4j configuration
+# Required only when GRAPH_BACKEND=graphiti_local
+# Note: the local Graphiti backend stores all graphs in one Neo4j database
+# and isolates each MiroFish graph by Graphiti `group_id`.
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your_neo4j_password
 ```
 
 #### 2. Install Dependencies
@@ -151,6 +163,17 @@ npm run setup:backend
 npm run dev
 ```
 
+If you use `GRAPH_BACKEND=graphiti_local`, start Neo4j too:
+
+```bash
+docker compose up -d neo4j
+```
+
+The bundled `docker-compose.yml` uses `neo4j:5.26.22-enterprise` with
+`NEO4J_ACCEPT_LICENSE_AGREEMENT=yes` as the safe local default.
+The current local backend still keeps all graphs in the default Neo4j database
+and maps each MiroFish `graph_id` directly to a Graphiti `group_id`.
+
 **Service URLs:**
 - Frontend: `http://localhost:3000`
 - Backend API: `http://localhost:5001`
@@ -175,11 +198,12 @@ docker compose up -d
 Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 (backend)`
 
 > Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
+> When `GRAPH_BACKEND=graphiti_local`, the bundled compose stack starts a local Neo4j instance for Graphiti storage. The repo keeps the enterprise image as the default compose target because existing local stores may use the block format.
 
 ## 📬 Join the Conversation
 
 <div align="center">
-<img src="./static/image/QQ群.png" alt="QQ Group" width="60%"/>
+<img src="./static/image/qq-group.png" alt="QQ Group" width="60%"/>
 </div>
 
 &nbsp;
@@ -200,4 +224,4 @@ MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interacti
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
  </picture>
-</a>
+</a>