From 9a77b5921d12d3380042e8581350f16cc646026f Mon Sep 17 00:00:00 2001 From: Dominik Seemann Date: Wed, 6 May 2026 17:38:44 +0200 Subject: [PATCH] docs: update CLAUDE.md and resolve README merge conflicts (Step 1) Bring repo docs in line with the Graphiti+Neo4j migration and prepare the codebase for Spec-Driven Development. CLAUDE.md: - Promote Neo4j + Graphiti to primary memory/graph layer; mark Zep Cloud as deprecated / compat-only. - Document the full env-var surface: NEO4J_*, EMBEDDING_MODEL, optional LLM_BOOST_* block. - Codify must-respect implementation rules (Task model for long ops, reasoning-output stripping, simulation IPC, subprocess cleanup, startup recovery, per-project group_id isolation, chat prefix injection). - Note i18n (vue-i18n + /locales/) and Docker prerequisite for dev. README.md / README-EN.md / README-ZH.md: - Resolve unresolved merge-conflict markers in README.md left over from the feat/graphiti-neo4j-migration merge (file was broken Markdown). - Lead with Docker as the recommended deployment path; keep source install as a documented alternative. - Replace Zep env vars with NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD / EMBEDDING_MODEL across all three READMEs. - Add optional LLM_BOOST_* block with omit-if-unused note. - Fix language-switcher links between the three READMEs. .claude/onboarding/step1_codebase/: - Document repo analysis, CLAUDE.md conventions decisions, and README resolution choices. --- .../step1_codebase/01_repo_analysis.md | 49 +++++++++++ .../step1_codebase/02_conventions.md | 66 ++++++++++++++ .../step1_codebase/03_readme_decisions.md | 69 +++++++++++++++ CLAUDE.md | 85 ++++++++++++++----- README-EN.md | 50 +++++++---- README-ZH.md | 74 ++++++++++++---- README.md | 85 +++++++++---------- 7 files changed, 374 insertions(+), 104 deletions(-) create mode 100644 .claude/onboarding/step1_codebase/01_repo_analysis.md create mode 100644 .claude/onboarding/step1_codebase/02_conventions.md create mode 100644 .claude/onboarding/step1_codebase/03_readme_decisions.md diff --git a/.claude/onboarding/step1_codebase/01_repo_analysis.md b/.claude/onboarding/step1_codebase/01_repo_analysis.md new file mode 100644 index 00000000..b7a7a791 --- /dev/null +++ b/.claude/onboarding/step1_codebase/01_repo_analysis.md @@ -0,0 +1,49 @@ +# Step 1 — Repo Analysis (Brownfield) + +## Project: MiroFish +Multi-Agent Swarm Intelligence Prediction Engine. + +## Date: 2026-05-06 + +## Findings + +### Top-level Structure +``` +MiroFish/ +├── .claude/ # Claude Code config (Step 0 set up) +├── .codegraph/ # local index, gitignored +├── .github/workflows/ # CI +├── backend/ # Python (Flask, uv) +│ ├── app/{api,services,models,utils,config} +│ ├── pyproject.toml, requirements.txt, run.py, uv.lock +│ └── scripts/ +├── frontend/ # Vue 3 + Vite +│ ├── src/{api,components,views,router,store,i18n,assets} +│ ├── package.json, vite.config.js, index.html +│ └── public/ +├── locales/, static/ +├── package.json # root orchestrator (concurrent dev) +├── docker-compose.yml, Dockerfile +├── README.md, README-EN.md, README-ZH.md +├── CLAUDE.md +└── LICENSE +``` + +### Decisions + +| Question | Decision | +|----------|----------| +| Q1 — Structure changes? | **No changes**. Existing layout is intentional and aligns with the layer-based convention from the Salestech Dev Guidelines. | +| Q2 — Create `docs/`? | **No**. Documentation stays in `README*.md`, `CLAUDE.md`, and `.claude/onboarding/`. | +| Q3 — Keep `.claude/`? | **Yes, keep as-is** (configured during Step 0). | +| Q4 — `.gitignore` additions? | **No further changes**. Step 0 already updated `.gitignore` to track project-level `.claude/` and ignore `settings.local.json` and `.codegraph/`. | +| Q5 — Trilingual README? | **Keep** the three READMEs (`README.md` = English default, `README-EN.md` = explicit EN, `README-ZH.md` = Chinese). | + +### Already Configured (from Step 0) +- `.claude/settings.json` — permissions (allow safe bash, deny secrets / destructive cmds) +- `.claude/rules/` — markdown, file-paths, commits, error-handling, dev-guidelines +- `.gitignore` — tracks project-level `.claude/`, ignores `settings.local.json` + `.codegraph/` + +## Next +- **PROMPT 2:** Review / update `CLAUDE.md` (tech stack, conventions, architecture, commands). +- **PROMPT 3:** Review / update `README.md` (prerequisites, env vars, install). diff --git a/.claude/onboarding/step1_codebase/02_conventions.md b/.claude/onboarding/step1_codebase/02_conventions.md new file mode 100644 index 00000000..b50846ca --- /dev/null +++ b/.claude/onboarding/step1_codebase/02_conventions.md @@ -0,0 +1,66 @@ +# Step 1 — CLAUDE.md Conventions Decisions + +Decisions made while updating `CLAUDE.md` (Step 1, PROMPT 2). + +## Date: 2026-05-06 + +## Drivers +The recent merge `feat/graphiti-neo4j-migration` (commit `6264828`) +replaced Zep Cloud with **Neo4j + Graphiti** as the primary +knowledge-graph store. The previous CLAUDE.md was out of date. + +## Section-by-Section Decisions + +### Tech Stack +- **Memory/Graph (UPDATED):** Primary = **Neo4j + Graphiti** (`graphiti-core>=0.3`). + Zep Cloud is now legacy / kept for backwards compatibility only. Code + files still named `zep_*` are historical artefacts; the underlying + store is Neo4j. +- **Versions added:** Vue 3.5, Vite 7, axios 1.14, vue-router 4.6, + vue-i18n 11, D3 7, camel-oasis 0.2.5, camel-ai 0.2.78. +- **i18n:** Documented `vue-i18n` + `/locales/{en,zh,languages}.json`. + +### Required Environment Variables +Updated to reflect `app/config.py`: +- Added: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, `EMBEDDING_MODEL`. +- Added: optional `LLM_BOOST_*` block (omit entirely if unused). +- Marked `ZEP_API_KEY` as deprecated/compat (empty string OK). + +### Conventions (per user direction) +- **Follow the conventions already established in this project.** +- Don't impose external style guides on existing code. +- 4-space indent, snake_case in Python; comments/docstrings mix English + and Chinese — both styles must continue to work. +- No enforced formatter or linter — match the surrounding file. +- New tooling decisions (Ruff, Prettier, etc.) require discussion before + adoption. + +### Architecture — Must-Respect Rules +Confirmed all architectural patterns drawn from the actual code: +1. Background tasks via `Task` model (status + progress polling). +2. Reasoning-model output stripping (`` tags, code fences). +3. Simulation IPC via `simulation_ipc.py`. +4. Subprocess cleanup via `SimulationRunner.register_cleanup()`. +5. Startup recovery via `_recover_stuck_projects()`. +6. Per-project graph isolation via `group_id` (Neo4j-specific). +7. Chat prefix injection to suppress tool calls in user-visible + responses. + +### Commands +- Added a note that `npm run dev` requires Neo4j running. +- Added a note that no lint/format command is configured. +- Clarified that pytest currently has only one script-style test + (`backend/scripts/test_profile_format.py`). + +## What's Now in CLAUDE.md +- Project overview (unchanged). +- Commands (with Neo4j prerequisite note + lint disclaimer). +- Tech stack (Neo4j+Graphiti primary, Zep deprecated, full versions). +- Required env vars (Neo4j block, optional boost block, deprecated zep). +- 5-step pipeline (rephrased to mention Graphiti+Neo4j). +- Backend / frontend structure (added i18n, locale, logger to utils). +- Key implementation conventions (the seven must-respect rules). +- Coding conventions (project-internal, no external imposition). + +## Next +- **PROMPT 3:** Review / update `README.md`. diff --git a/.claude/onboarding/step1_codebase/03_readme_decisions.md b/.claude/onboarding/step1_codebase/03_readme_decisions.md new file mode 100644 index 00000000..fd6b3541 --- /dev/null +++ b/.claude/onboarding/step1_codebase/03_readme_decisions.md @@ -0,0 +1,69 @@ +# Step 1 — README Decisions + +Decisions made while reviewing / repairing the READMEs (Step 1, PROMPT 3). + +## Date: 2026-05-06 + +## Critical Finding +`README.md` contained **unresolved git merge conflict markers** +(`<<<<<<< HEAD` / `=======` / `>>>>>>>`) at two locations: the +prerequisites table and the env-vars block. These were left over from +the recent `feat/graphiti-neo4j-migration` merge (commit `6264828`) and +needed to be resolved as part of Step 1. + +`README-EN.md` and `README-ZH.md` did **not** have markers but the ZH +file still referenced Zep Cloud (out of date). + +## Decisions + +| Question | Decision | +|----------|----------| +| Q1 — Resolve conflicts? | **Take Neo4j-branch content** (Neo4j prerequisite + Neo4j env vars). Zep references removed. | +| Q2 — Prerequisites refinement? | **Out of scope for now.** Kept Neo4j install instructions as-is, will be revisited separately. | +| Q3 — Add `LLM_BOOST_*` to README env vars? | **Yes.** Added as an optional block with a note to omit entirely if not used (matches `.env.example`). | +| Q4 — Installation flow? | **Always assume Docker.** Reordered: Docker is now Option 1 (Recommended); Source is Option 2. | +| Q5 — Sync three READMEs? | **Yes.** All three updated to reflect Neo4j and Docker-first install. | + +## What Changed + +### `README.md` (English default) +- Resolved both merge conflict regions (prerequisites + env vars). +- Reordered: **Docker first** (Option 1, recommended), Source second + (Option 2). +- Added `LLM_BOOST_*` optional env-var block with omit-if-unused note. +- Removed the redundant note at end of source-deploy block. + +### `README-EN.md` (explicit English) +- Fixed language switcher: was `[English](./README-EN.md) | [中文文档](./README.md)` — now points to the correct files (`README.md` is English, `README-ZH.md` is Chinese). +- Reordered Docker-first / Source-second to match `README.md`. +- Added `LLM_BOOST_*` optional block. + +### `README-ZH.md` (Chinese) +- Removed Zep Cloud env-var section. +- Added Neo4j prerequisite row + install instructions (translated). +- Added `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` / + `EMBEDDING_MODEL` env-var block (translated). +- Reordered Docker-first / Source-second to match `README.md`. +- Added `LLM_BOOST_*` optional block (translated). +- Added the migration note (Zep → Graphiti + Neo4j) in Chinese. + +## Verification +- `grep` for `<<<<<<<` / `>>>>>>>` / `=======` across all three READMEs + and `CLAUDE.md` returned no matches. +- All three files are valid Markdown. +- Language-switcher links between the three files are now consistent. + +## Step 1 — Complete +Outputs: +- `.claude/onboarding/step1_codebase/01_repo_analysis.md` +- `.claude/onboarding/step1_codebase/02_conventions.md` +- `.claude/onboarding/step1_codebase/03_readme_decisions.md` + +Updated files: +- `CLAUDE.md` (Neo4j+Graphiti primary, Zep deprecated, full env vars, + must-respect rules, project-internal coding conventions). +- `README.md` / `README-EN.md` / `README-ZH.md` (Docker-first flow, + Neo4j env vars, optional LLM_BOOST, language-switcher fixed). + +## Next +- Step 2: Claude Setup (settings.json, hooks, permissions) diff --git a/CLAUDE.md b/CLAUDE.md index 43711aa2..dcbebdf4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,10 @@ npm run backend # Backend only: Flask on port 5001 npm run frontend # Frontend only: Vite on port 3000 ``` +> **Prerequisite:** Neo4j must be running (default `bolt://localhost:7687`). +> The Graphiti-based knowledge graph requires it. Use `docker-compose up` +> for the full stack including Neo4j. + ### Build ```bash npm run build # Build frontend (Vite) @@ -30,7 +34,7 @@ npm run build # Build frontend (Vite) ### Backend (Python) ```bash cd backend && uv run python run.py # Start Flask server -cd backend && uv run python -m pytest # Run tests (if any) +cd backend && uv run python -m pytest # Run tests (currently scripts/test_profile_format.py only) ``` ### Docker @@ -38,39 +42,59 @@ cd backend && uv run python -m pytest # Run tests (if any) docker-compose up # Full stack via Docker ``` +> **Lint/format:** No linter or formatter is configured in this project. +> Match the existing style of the file you're editing. + ## Architecture ### Stack -- **Backend**: Python ≥3.11 Flask 3.0, managed by `uv` -- **Frontend**: Vue 3 + Vite, port 3000; proxies `/api` → port 5001 -- **LLM**: OpenAI SDK-compatible (default: Qwen via `dashscope`; also works with GLM, OpenAI) -- **Memory/Graph**: Zep Cloud (knowledge graph for entity storage and retrieval) -- **Simulation**: CAMEL-OASIS (multi-agent Twitter + Reddit simulation) -- **Visualization**: D3.js +- **Backend**: Python ≥3.11, Flask 3.0, managed by `uv` +- **Frontend**: Vue 3.5 + Vite 7, port 3000; proxies `/api` → port 5001 +- **LLM**: OpenAI SDK-compatible (default: Qwen via `dashscope`; also works with GLM, OpenAI, Gemini) +- **Memory/Graph**: **Neo4j + Graphiti** (`graphiti-core>=0.3`) — primary store for the knowledge graph (entities/edges scoped by `group_id` per project) +- **Memory/Graph (deprecated)**: Zep Cloud — legacy code path; new code should not depend on it. Several services still carry the `zep_*` filename prefix for historical reasons (`zep_tools.py`, `zep_entity_reader.py`, `zep_graph_memory_updater.py`). +- **Simulation**: CAMEL-OASIS 0.2.5 + camel-ai 0.2.78 (multi-agent Twitter + Reddit simulation) +- **Visualization**: D3.js 7 +- **i18n**: `vue-i18n` (frontend) + per-locale JSON in `/locales/` (`en.json`, `zh.json`, `languages.json`); backend logger messages translated as part of the i18n initiative ### Required Environment Variables Copy `.env.example` to `.env`: ``` -LLM_API_KEY # Required -LLM_BASE_URL # Default: https://dashscope.aliyuncs.com/compatible-mode/v1 -LLM_MODEL_NAME # Default: qwen-plus -ZEP_API_KEY # Required (Zep Cloud) +# LLM (OpenAI SDK-compatible) +LLM_API_KEY # Required +LLM_BASE_URL # Default: https://dashscope.aliyuncs.com/compatible-mode/v1 +LLM_MODEL_NAME # Default: qwen-plus + +# Neo4j + Graphiti (knowledge graph) +NEO4J_URI # Default: bolt://localhost:7687 +NEO4J_USER # Default: neo4j +NEO4J_PASSWORD # Default: mirofish123 (override in real env) +EMBEDDING_MODEL # Default: text-embedding-3-small + # Override for non-OpenAI providers (e.g. Gemini: text-embedding-004) + +# Optional — Accelerated LLM (omit entirely if not used) +LLM_BOOST_API_KEY +LLM_BOOST_BASE_URL +LLM_BOOST_MODEL_NAME + +# Deprecated, kept for backwards compat +ZEP_API_KEY # Empty string acceptable ``` ### 5-Step Pipeline The core workflow is a sequential async pipeline: -1. **Graph Build** — Upload files → LLM extracts ontology → Zep Cloud builds knowledge graph -2. **Env Setup** — Read Zep entities → Generate OASIS agent profiles (AI personalities) +1. **Graph Build** — Upload files → LLM extracts ontology → Graphiti writes nodes/edges to Neo4j (scoped by per-project `group_id`) +2. **Env Setup** — Read entities from Neo4j → Generate OASIS agent profiles (AI personalities) 3. **Simulation** — CAMEL-OASIS runs agents on dual platforms (Twitter + Reddit) in parallel -4. **Report** — ReportAgent (ReACT loop) queries graph with tools: `SearchResult`, `InsightForge`, `Panorama`, `Interview` -5. **Interaction** — Chat with simulated agents or the ReportAgent +4. **Report** — `ReportAgent` (ReACT loop) queries the graph with tools: `SearchResult`, `InsightForge`, `Panorama`, `Interview` +5. **Interaction** — Chat with simulated agents or the `ReportAgent` ### Backend Structure (`backend/app/`) - `api/` — Flask blueprints: `graph_bp`, `simulation_bp`, `report_bp` -- `services/` — Core logic: graph building, simulation runner, report agent, Zep tools +- `services/` — Core logic: graph building, simulation runner, report agent, Graphiti adapter, legacy Zep tools - `models/` — `Project` and `Task` state objects (in-memory, JSON-serializable) -- `utils/` — LLM client wrapper, file parser, retry logic, Zep pagination -- `config/config.py` — All configuration (LLM, Zep, chunking, simulation params) +- `utils/` — LLM client wrapper, file parser, retry logic, Zep pagination, locale helpers, logger +- `config.py` — All configuration (LLM, Neo4j, embedding, chunking, OASIS, ReportAgent params) Long-running operations (ontology generation, graph build, profile generation, report generation) run as background tasks tracked via `Task` objects with progress polling. @@ -78,9 +102,24 @@ Long-running operations (ontology generation, graph build, profile generation, r - `views/` — Page components mapped to routes; `Process.vue` is the main 50KB workflow orchestrator - `components/` — `Step1-5` step components + `GraphPanel.vue` (D3 graph visualization) - `api/` — Axios services (`graph.js`, `simulation.js`, `report.js`) with 5-min timeout and exponential retry +- `i18n/` — Locale loader; messages in repo-root `/locales/` +- `router/`, `store/`, `assets/` -### Key Implementation Details -- Reasoning model outputs (e.g., MiniMax/GLM with `` tags or markdown code fences) are stripped before processing — see recent fix in commit `985f89f` -- Simulation state is managed in `SimulationManager`; IPC between processes via `simulation_ipc.py` -- Interview/chat with agents uses prefix injection to suppress tool calls in responses -- Default simulation: max 10 rounds, Twitter actions include CREATE_POST/LIKE/REPOST/FOLLOW/QUOTE/DO_NOTHING; Reddit adds CREATE_COMMENT/DISLIKE +### Key Implementation Conventions + +These are conventions **established by this project**. Match them when adding new code. + +- **Background tasks via `Task` model** — Any operation that takes more than a few seconds (ontology gen, graph build, profile gen, simulation, report) must be tracked through `Task` with status + progress fields and exposed via a polling endpoint. +- **Reasoning-model output stripping** — Reasoning-model outputs (e.g. MiniMax/GLM with `` tags or markdown code fences) must be stripped before JSON parsing. See the fix in commit `985f89f`. +- **Simulation IPC via `simulation_ipc.py`** — Inter-process communication between the Flask app and simulation subprocesses goes through this module; do not call subprocess primitives directly elsewhere. +- **Subprocess cleanup** — `SimulationRunner.register_cleanup()` is invoked at app start so simulation subprocesses are terminated on shutdown. Don't bypass it. +- **Startup recovery (`_recover_stuck_projects`)** — On boot, projects stuck in `GRAPH_BUILDING` are auto-recovered to `GRAPH_COMPLETED` if Neo4j already has their nodes (the original task was killed by a restart). New code paths that introduce long-running tasks should follow the same recovery pattern. +- **Per-project graph isolation** — All Neo4j/Graphiti queries must filter by the project's `group_id`. Cross-project graph access is not permitted. +- **Interview / chat prefix injection** — Agent chat suppresses tool calls in user-visible responses via prefix injection. Preserve this when extending chat behavior. +- **Default simulation parameters** — Max 10 rounds. Twitter actions: `CREATE_POST`, `LIKE_POST`, `REPOST`, `FOLLOW`, `QUOTE_POST`, `DO_NOTHING`. Reddit adds `CREATE_COMMENT`, `LIKE_COMMENT`, `DISLIKE_*`, `SEARCH_*`, `TREND`, `REFRESH`, `MUTE`. Configured in `app/config.py`. + +### Coding Conventions +- Follow the conventions already established in this project — match the surrounding file's style. +- 4-space indentation, snake_case in Python; existing code mixes English and Chinese in comments/docstrings — keep both styles working. +- Use type hints where the surrounding code uses them; otherwise match local style. +- For new tooling decisions (lint, format, test runners), discuss before adding — the project intentionally has no enforced formatter at present. diff --git a/README-EN.md b/README-EN.md index 8290ff13..b45efa3d 100644 --- a/README-EN.md +++ b/README-EN.md @@ -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) +[English](./README.md) | [中文文档](./README-ZH.md) @@ -93,7 +93,24 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on ## 🚀 Quick Start -### Option 1: Source Code Deployment (Recommended) +### Option 1: Docker Deployment (Recommended) + +The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command. + +```bash +# 1. Copy and configure environment variables +cp .env.example .env +# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default) + +# 2. Pull images and start +docker compose up -d +``` + +Reads `.env` from the project root, exposes ports `3000` (frontend) and `5001` (backend). + +> A faster mirror address is provided as a comment inside `docker-compose.yml`; uncomment to use it. + +### Option 2: Source Code Deployment #### Prerequisites @@ -145,11 +162,22 @@ NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your_neo4j_password -# Embedding model (uncomment if using Gemini API) +# Embedding model (uncomment if using a non-OpenAI provider, e.g. Gemini) # EMBEDDING_MODEL=gemini-embedding-001 ``` -> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party account required — completely free with no rate limits. +**Optional — Accelerated LLM Configuration:** + +If you have a faster/cheaper provider, you can route auxiliary calls through it. +**Omit these entirely** if not used (do not leave placeholder values). + +```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 +``` + +> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party knowledge-graph account is required — completely free with no rate limits. #### 2. Install Dependencies @@ -186,20 +214,6 @@ npm run backend # Start backend only npm run frontend # Start frontend only ``` -### Option 2: Docker Deployment - -```bash -# 1. Configure environment variables (same as source deployment) -cp .env.example .env - -# 2. Pull image and start -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. - ## 📬 Join the Conversation
diff --git a/README-ZH.md b/README-ZH.md index 0b20424d..e9ea806d 100644 --- a/README-ZH.md +++ b/README-ZH.md @@ -93,7 +93,24 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体 ## 🚀 快速开始 -### 一、源码部署（推荐） +### 一、Docker 部署（推荐） + +Docker 部署一键启动整个栈 —— 前端、后端和 Neo4j。 + +```bash +# 1. 复制并配置环境变量 +cp .env.example .env +# 编辑 .env，填入 LLM_API_KEY（如需覆盖默认 Neo4j 密码也一并修改） + +# 2. 拉取镜像并启动 +docker compose up -d +``` + +默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）`。 + +> 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换。 + +### 二、源码部署 #### 前置要求 @@ -102,6 +119,24 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体 | **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` | | **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` | | **uv** | 最新版 | Python 包管理器 | `uv --version` | +| **Neo4j** | 5.x Community | 本地知识图谱数据库 | `neo4j --version` | + +**安装 Neo4j（选择适合你的方式）：** + +```bash +# macOS +brew install neo4j + +# Linux (Debian/Ubuntu) +# 参考官方文档：https://neo4j.com/docs/operations-manual/current/installation/linux/ + +# Windows / 所有平台 +# 下载 Desktop 版本：https://neo4j.com/download/ + +# 首次启动前设置密码，然后启动服务 +neo4j-admin dbms set-initial-password your_neo4j_password +neo4j start +``` #### 1. 配置环境变量 @@ -122,11 +157,28 @@ LLM_API_KEY=your_api_key LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL_NAME=qwen-plus -# Zep Cloud 配置 -# 每月免费额度即可支撑简单使用：https://app.getzep.com/ -ZEP_API_KEY=your_zep_api_key +# 知识图谱配置（本地 Neo4j + Graphiti，免费无限制） +NEO4J_URI=bolt://localhost:7687 +NEO4J_USER=neo4j +NEO4J_PASSWORD=your_neo4j_password + +# Embedding 模型（使用非 OpenAI 厂商时取消注释，例如 Gemini） +# EMBEDDING_MODEL=gemini-embedding-001 ``` +**可选 —— 加速 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 +``` + +> **注意：** MiroFish 已从 Zep Cloud 迁移至本地 **Graphiti + Neo4j**，无需注册任何第三方知识图谱服务，完全免费且无速率限制。 + #### 2. 安装依赖 ```bash @@ -162,20 +214,6 @@ npm run backend # 仅启动后端 npm run frontend # 仅启动前端 ``` -### 二、Docker 部署 - -```bash -# 1. 配置环境变量（同源码部署） -cp .env.example .env - -# 2. 拉取镜像并启动 -docker compose up -d -``` - -默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）` - -> 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换 - ## 📬 更多交流
diff --git a/README.md b/README.md index f98741d6..383a036d 100644 --- a/README.md +++ b/README.md @@ -93,41 +93,50 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on ## 🚀 Quick Start -### Option 1: Source Code Deployment (Recommended) +### Option 1: Docker Deployment (Recommended) + +The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command. + +```bash +# 1. Copy and configure environment variables +cp .env.example .env +# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default) + +# 2. Pull images and start +docker compose up -d +``` + +Reads `.env` from the project root, exposes ports `3000` (frontend) and `5001` (backend). + +> A faster mirror address is provided as a comment inside `docker-compose.yml`; uncomment to use it. + +### Option 2: Source Code Deployment #### Prerequisites -<<<<<<< HEAD | Tool | Version | Description | Check Installation | |------|---------|-------------|-------------------| | **Node.js** | 18+ | Frontend runtime, includes npm | `node -v` | | **Python** | ≥3.11, ≤3.12 | Backend runtime | `python --version` | | **uv** | Latest | Python package manager | `uv --version` | -======= -| 工具 | 版本要求 | 说明 | 安装检查 | -|------|---------|------|---------| -| **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` | -| **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` | -| **uv** | 最新版 | Python 包管理器 | `uv --version` | -| **Neo4j** | 5.x Community | 本地知识图谱数据库 | `neo4j --version` | +| **Neo4j** | 5.x Community | Local knowledge graph database | `neo4j --version` | -**安装 Neo4j（选择适合你的方式）：** +**Install Neo4j (choose one):** ```bash # macOS brew install neo4j # Linux (Debian/Ubuntu) -# 参考官方文档：https://neo4j.com/docs/operations-manual/current/installation/linux/ +# See official docs: https://neo4j.com/docs/operations-manual/current/installation/linux/ -# Windows / 所有平台 -# 下载 Desktop 版本：https://neo4j.com/download/ +# Windows / All platforms +# Download Neo4j Desktop: https://neo4j.com/download/ -# 首次启动前设置密码，然后启动服务 +# Set password before first start, then launch neo4j-admin dbms set-initial-password your_neo4j_password neo4j start ``` ->>>>>>> abhiyadav2345/feat/graphiti-neo4j-migration #### 1. Configure Environment Variables @@ -148,29 +157,29 @@ LLM_API_KEY=your_api_key LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL_NAME=qwen-plus -<<<<<<< HEAD -# Zep Cloud Configuration -# Free monthly quota is sufficient for simple usage: https://app.getzep.com/ -ZEP_API_KEY=your_zep_api_key -``` - -#### 2. Install Dependencies -======= -# 知识图谱配置（本地 Neo4j + Graphiti，免费无限制） -# 安装 Neo4j Community Edition：https://neo4j.com/download/ -# macOS 用户：brew install neo4j && neo4j start +# Knowledge Graph — local Neo4j + Graphiti (free, no rate limits) NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your_neo4j_password -# Embedding 模型（使用 Gemini API 时取消注释） +# Embedding model (uncomment if using a non-OpenAI provider, e.g. Gemini) # EMBEDDING_MODEL=gemini-embedding-001 ``` -> **注意：** MiroFish 已从 Zep Cloud 迁移至本地 **Graphiti + Neo4j**，无需注册任何第三方服务，完全免费且无速率限制。 +**Optional — Accelerated LLM Configuration:** -#### 2. 安装依赖 ->>>>>>> abhiyadav2345/feat/graphiti-neo4j-migration +If you have a faster/cheaper provider, you can route auxiliary calls through it. +**Omit these entirely** if not used (do not leave placeholder values). + +```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 +``` + +> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party knowledge-graph account is required — completely free with no rate limits. + +#### 2. Install Dependencies ```bash # One-click installation of all dependencies (root + frontend + backend) @@ -205,20 +214,6 @@ npm run backend # Start backend only npm run frontend # Start frontend only ``` -### Option 2: Docker Deployment - -```bash -# 1. Configure environment variables (same as source deployment) -cp .env.example .env - -# 2. Pull image and start -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. - ## 📬 Join the Conversation
@@ -243,4 +238,4 @@ MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interacti Star History Chart - \ No newline at end of file +