User guide

Get started with MicroWorld

This page keeps the setup path short: clone the repository, configure the required environment variables, run the backend, and execute the pipeline with your own local input package.

Quick start

Five steps to a local run

These are the shortest steps that map directly to the current repository layout.

Clone the repository

Download the project and enter the repository root.

              git clone https://github.com/d2i-cuhksz/MicroWorld.git
cd MicroWorld
            

Create a root `.env`

The backend validates at least two required keys before startup.

              cp .env.example .env

LLM_API_KEY=your_key
ZEP_API_KEY=your_key

# Optional
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
MULTIMODAL_AUDIO_API_KEY=
MULTIMODAL_AUDIO_BASE_URL=
            

Install backend dependencies

The current repository expects dependency management through uv. If you plan to ingest video inputs, make sure ffmpeg and ffprobe are available too.

uv sync

Start the API service

This brings up the Flask backend that serves the graph, simulation, and report endpoints.

uv run microworld-api

Create a run config and launch the workflow

Start from the public template, point it to your own local input files, and then run the full pipeline from the repository root.

              cp configs/full_run/full_run.template.json /tmp/microworld-run.json

uv run microworld-full-run \
  --config /abs/path/to/microworld-run.json
            

Useful commands

Main entry points

API service

uv run microworld-api

Local graph pipeline

uv run microworld-local-pipeline --config ...

Parallel simulation

uv run microworld-parallel-sim --config ...

Full run

uv run microworld-full-run --config ...

Notes

What to expect from the current repo

What is already ready

Backend API skeleton and routes
Config templates for local runs
Generated simulation artifacts and reports
Static GitHub Pages project site

Good places to start

Read the architecture page for the full workflow
Open the examples page to see the LK-99 demo
Run `microworld-full-run` for the end-to-end pipeline
Inspect the generated report and simulation artifacts