# MiroFish Verified User Guide

> Scope: the current `main` branch of the open-source [`666ghj/MiroFish`](https://github.com/666ghj/MiroFish) project.
>
> This guide distinguishes behavior stated in the official README from interaction verified in the current frontend source. Labels, screenshots, and deployment details can change; when they differ, use the current upstream code and the running application as the final reference.

## Quick answer

MiroFish has five upstream workflow stages:

1. Graph Building
2. Environment Setup
3. Simulation
4. Report Generation
5. Deep Interaction

For a first run, do not begin with a long simulation. Use a public, moderately sized source packet, complete one small pilot, and then inspect the graph, personas, and action logs. The official README notes that model usage can be expensive and recommends trying fewer than 40 rounds first.

## Sources and verification level

| Topic | Evidence | Verification level |
| --- | --- | --- |
| Five-stage workflow, prerequisites, launch commands, Docker path | [Official Chinese README](https://github.com/666ghj/MiroFish/blob/main/README-ZH.md) | Official project documentation |
| Required environment variables and optional acceleration variables | [`.env.example`](https://github.com/666ghj/MiroFish/blob/main/.env.example) | Current source code |
| Upload entry point, supported file types, and start condition | [`Home.vue`](https://github.com/666ghj/MiroFish/blob/main/frontend/src/views/Home.vue) | Current frontend source |
| Graph, environment, simulation, reporting, and chat components | [Frontend component directory](https://github.com/666ghj/MiroFish/tree/main/frontend/src/components) | Current frontend source |
| Upstream workflow examples | [Wuhan public-opinion demo](https://www.bilibili.com/video/BV1VYBsBHEMY/) and [Dream of the Red Chamber demo](https://www.bilibili.com/video/BV1cPk3BBExq) | Linked from the official README; reference only |

The `index.html` in this folder is an offline visual reconstruction. It does not connect to a MiroFish service, upload a file, or make a model request.

## 0. Prerequisites

### Runtime requirements

The current official README lists the following requirements:

| Tool or service | Requirement |
| --- | --- |
| Node.js | Version 18 or later |
| Python | Version 3.11 through 3.12 |
| uv | Latest version |
| LLM provider | An API compatible with the OpenAI SDK format |
| Memory graph | Zep Cloud API key |

### Prepare before starting

1. Prepare one or more source files. The current upload control accepts `.pdf`, `.md`, and `.txt`.
2. Frame a testable question instead of asking only “what will happen?” For example:

   ```text
   Explore how market awareness, opposing narratives, and prospective customer reactions may change when a product enters a new market next quarter.
   Time horizon: 120 hours.
   Constraints: use only the supplied material; compare price sensitivity, supply constraints, and policy signals.
   ```

3. Obtain a working LLM API key and Zep Cloud API key. Never commit real keys, include them in screenshots, or place them in reports.

### Configure environment variables

From the MiroFish project root, create the local environment file:

```bash
cp .env.example .env
```

Fill the required values without exposing their actual contents:

```env
LLM_API_KEY=...
LLM_BASE_URL=...
LLM_MODEL_NAME=...
ZEP_API_KEY=...
```

The current `.env.example` also lists optional `LLM_BOOST_*` values. When you do not use the acceleration path, do not leave empty placeholder settings that could create ambiguous behavior.

## 1. Deploy and start the application

### Option A: source deployment (officially recommended)

```bash
npm run setup:all
npm run dev
```

You can also install the layers separately:

```bash
npm run setup
npm run setup:backend
```

The official README lists these default services:

- Frontend: `http://localhost:3000`
- Backend API: `http://localhost:5001`

They can be started separately:

```bash
npm run backend
npm run frontend
```

### Option B: Docker

Complete the `.env` configuration first, then run:

```bash
docker compose up -d
```

The README states that the default mapping exposes frontend port `3000` and backend port `5001`.

## 2. End-to-end operating workflow

### Start: upload source material and describe the requirement

1. Open the homepage.
2. In **Reality Seed**, drop or choose a PDF, Markdown, or TXT file.
3. In **Simulation Requirement**, write:
   - the outcome you want to observe;
   - the time horizon;
   - known constraints;
   - the variables or roles you care about; and
   - the scenarios you want to compare.
4. Confirm that at least one file is attached and the requirement is not blank, then start the engine.

In the current frontend source, a run cannot be submitted until both an uploaded file and a non-empty requirement are present. `Home.vue` implements that check through `canSubmit`.

### Stage 1: wait for and review Graph Building

The interface presents three consecutive operations:

1. **Ontology Generation** — creates entity types, attributes, and relationship types.
2. **GraphRAG Build** — extracts entities, edges, and facts from chunked material.
3. **Create Simulation** — creates a simulation instance after the graph is complete.

Review the following before continuing:

- Are the key people, organizations, events, and concepts present?
- Do the relationship types match the material rather than appearing invented?
- Are there irrelevant or duplicate entities?
- Do the graph’s node and relationship counts look wildly implausible?

If the graph is weak, first improve the source material or the simulation requirement and rebuild. Do not assume the engine code must be changed.

When the graph is complete, select **Enter Environment Setup**. The current source creates a simulation and enables two simulation environments.

### Stage 2: Environment Setup

This is the stage represented by the provided reference image. It contains three kinds of information:

1. **Simulation instance details** — project, graph, simulation, and task identifiers.
2. **Generated Agent Personas** — auto-generated role cards with interests, descriptions, and stances.
3. **Simulation Configuration** — simulation length, minutes per round, total rounds, active agents per hour, time windows, agent behaviors, and platform recommendation-algorithm settings.

Use this review order:

1. Open important graph nodes and confirm their entity details and relationships.
2. Open several persona cards and confirm that each role comes from the correct entity and fits the source material.
3. Check agent count, simulation duration, and total rounds.
4. Check whether activity windows and intensity fit the scenario.
5. Start with a small custom-round pilot. The upstream README recommends fewer than 40 rounds for an initial experiment.

The reference image shows the relationship graph on the left and personas/configuration on the right. The current upstream Vue code also provides a graph panel and `Step2EnvSetup` configuration; colors, layout, and exact fields can vary by version.

When the review is satisfactory, select **Start Dual-World Simulation**.

### Stage 3: monitor the dual-platform simulation

The current frontend presents two environments as **Info Plaza** and **Topic Community**, showing:

- current and total round;
- simulation time;
- action count; and
- an event feed containing posts, comments, reposts, quotes, follows, searches, and votes.

Recommended operating sequence:

1. Confirm that both platforms are running.
2. Check whether events match the persona setup and time windows.
3. Record abnormal patterns such as excessive idle actions, repetitive content, or reactions that are clearly unrelated to the input.
4. Wait until both platforms are completed before choosing **Start Generate Report**.

Do not treat an in-progress event stream as a final conclusion. A simulation output should be used as a scenario hypothesis and a set of possible paths, not as a factual prediction.

### Stage 4: generate and review the report

After you start report generation, ReportAgent analyzes the post-simulation environment. The current component displays planning, section generation, tool calls, and completion state.

Ask these questions while reviewing the report:

1. Does the summary state its assumptions and time horizon?
2. Can each key claim be traced to simulated events, agent responses, or graph relationships?
3. Does it incorrectly present generated wording as an external fact?
4. Which variables differ between its proposed paths?
5. Which finding is worth a one-variable comparison run?

Treat the report as an evidence-navigation layer, not a replacement for the evidence itself.

### Stage 5: Deep Interaction and the next experiment

After the report is complete, you can:

- continue the conversation with **ReportAgent** about a finding;
- select an individual simulated agent and ask about its motivation, judgment, or reaction;
- select several agents, ask them the same question, and compare group divergence; or
- change exactly one variable — for example price, duration, initial event, or constraint — and run a controlled comparison.

A useful follow-up question is:

```text
If the price falls by 20%, which path changes the most?
Identify the affected roles, related events, and simulation evidence supporting that finding.
```

## 3. Troubleshooting order

| Symptom | Check first | Next action |
| --- | --- | --- |
| Start button is unavailable | Is a supported file attached? Is the requirement blank? | Attach a supported file and complete the requirement text. |
| Graph entities are obviously irrelevant | Mixed source packet or overly broad question | Remove irrelevant material; constrain the time, population, and target. |
| Persona quality is poor | Incomplete graph entities or relationships | Return to Graph Building; improve the material or requirement and rebuild. |
| Simulation is costly or slow | Too many rounds, too many agents, or model latency | Start with a small pilot and expand one factor at a time. |
| Report is too generic | The requirement has no testable variables | Rewrite it as “variable + time horizon + target outcome + constraints.” |
| Findings cannot be verified | Only the summary was read | Inspect the event feed, role responses, and graph; then run a controlled comparison. |

## 4. Quality and safety boundaries

- Do not upload unnecessary personal information, confidential material, keys, or unlicensed source data.
- Remove sensitive identifiers before starting and confirm that you are authorized to handle the material.
- Treat MiroFish output as possible paths generated within a simulation. It is not a definite financial, legal, medical, political, personnel, or other high-stakes conclusion.
- For important decisions, retain the input-material version, model configuration, round count, report version, and relevant logs so the result can be reviewed.

## 5. Local demo timecode

| Timecode | Segment |
| --- | --- |
| 00:00–00:03 | Workspace opening |
| 00:03–00:14 | Folder selection and seed-file upload |
| 00:14–00:29 | Requirement typing and engine start |
| 00:29–00:45 | Ontology mapping and relationship-graph growth |
| 00:45–00:55 | Environment relationship and persona review |
| 00:55–01:18 | Persona/rule generation and pilot launch |
| 01:18–01:40 | Two-platform simulation and log growth |
| 01:40–02:06 | Report drafting and evidence linking |
| 02:06–02:30 | Follow-up question, reply, and next run |

Open `index.html` in the same folder and drag the timeline to jump directly to any stage.

All staged states are derived from the timeline position, so seeking backward or forward reconstructs the matching upload, graph, simulation, report, and interaction state without depending on one-off timers.