MiroMindAI · BinWang28 · Aug 26, 2025 · Aug 26, 2025 · Aug 26, 2025 · Aug 26, 2025
diff --git a/README.md b/README.md
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,15 @@
+**Q: What is the estimated cost of running the GAIA validation set for a single run?** <br>
+**A**: The cost is approximately **$450 USD** for a run without a cache. Enabling the cache can significantly reduce this cost by 50-67%, bringing it down to the **$150 - $225** range.
+
+
+**Q: How long does it take to run the GAIA validation set for a single run?** <br>
+**A**: With the `max_concurrent` parameter set to 20, a full run takes about **5 hours** to complete.
+
+**Q: Are all the specified APIs required?** <br>
+**A**: **Yes.** To fully reproduce our published results, access to all the listed APIs is necessary.
+
+
+**Q: What is the difference between MiroFlow and MiroThinker?** <br>
+**A**:  **MiroFlow** is primarily focused on interacting with proprietary models; **MiroThinker** is designed for our own open-source models.
+
+We plan to merge these two projects in the future to create a single, unified platform.
diff --git a/docs/figs/09xyHJV9dkbY2yacsv4zYTBbKM.avif b/docs/figs/09xyHJV9dkbY2yacsv4zYTBbKM.avif
diff --git a/docs/figs/MiroFlow_logo.png b/docs/figs/MiroFlow_logo.png
diff --git a/docs/figs/gaia_score.png b/docs/figs/gaia_score.png
diff --git a/docs/figs/logo.png b/docs/figs/logo.png
diff --git a/docs/figs/miroflow_architecture.png b/docs/figs/miroflow_architecture.png
diff --git a/docs/figs/wechat-bot-qr-code.jpg b/docs/figs/wechat-bot-qr-code.jpg
diff --git a/docs/figs/wechat-group-qr-code.jpg b/docs/figs/wechat-group-qr-code.jpg
diff --git a/docs/hydra_config.md b/docs/hydra_config.md
@@ -0,0 +1,71 @@
+
+### Structure
+
+```
+MiroFlow/libs/miroflow/src/miroflow/prebuilt/config
+├── config.yaml              # Main configuration with defaults
+├── agent/                   # Agent configurations (tools, limits)
+├── benchmark/               # Benchmark configurations (datasets, execution)
+└── llm/                     # Language model configurations (providers, models)
+```
+
+### Usage
+
+Run with default configuration:
+```bash
+cd MiroFlow/apps/run-agent
+uv run main.py common-benchmark
+```
+
+Default configuration is defined in  
+`MiroFlow/libs/miroflow/src/miroflow/prebuilt/config/config.yaml`:
+
+```yaml
+# conf/config.yaml
+defaults:
+  - llm: claude_openrouter
+  - agent: miroflow
+  - benchmark: gaia-validation
+  - pricing: _default
+
+# Other configurations...
+```
+
+| Component  | Default Value         | File Path                                                                 |
+|------------|----------------------|---------------------------------------------------------------------------|
+| LLM        | `claude_openrouter`  | `libs/miroflow/src/miroflow/prebuilt/config/llm/claude_openrouter.yaml`                                   |
+| Agent      | `miroflow`           | `libs/miroflow/src/miroflow/prebuilt/config/agent/miroflow.yaml`                        |
+| Benchmark  | `gaia-validation`    | `libs/miroflow/src/miroflow/prebuilt/config/benchmark/gaia-validation.yaml`                                       |
+
+
+### Override Configurations
+
+#### Component Override
+Switch between existing configurations using the filename (without `.yaml`):
+```bash
+uv run main.py common-benchmark llm=<filename> agent=<filename> benchmark=<filename>
+```
+
+For example, if you have `conf/llm/claude_openrouter.yaml`, use `llm=claude_openrouter`
+
+
+#### Parameter Override
+Override specific parameters:
+```bash
+cd MiroFlow/apps/run-agent
+uv run main.py common-benchmark llm.temperature=0.1 agent.main_agent.max_turns=30
+```
+
+### Create Custom Configurations
+
+1. **Create new config file** in the appropriate subdirectory (e.g., `conf/llm/my_config.yaml`)
+2. **Inherit from defaults** using Hydra's composition:
+   ```yaml
+   defaults:
+     - _default  # Inherit base configuration
+     - _self_    # Allow self-overrides
+
+   # Your custom parameters
+   parameter: value
+   ```
+3. **Use your config**: `uv run main.py common-benchmark component=my_config`
diff --git a/docs/local_e2b.md b/docs/local_e2b.md
@@ -0,0 +1,39 @@
+
+# Prepare E2B Sandbox (Optional)
+
+> [!TIP]
+> We provide a public E2B sandbox template. Follow this step if you want to reproduce.
+>
+> For the E2B sandbox service, we recommend setting up a Linux Docker image with a comprehensive set of apt and Python packages pre-installed. Without these pre-installed packages, the agent will need to spend extra steps and context installing them, resulting in reduced token efficiency.
+>
+> you need to have `npm` install and `docker` running locally.
+
+
+1. Install `e2b` command line and login:
+
+```shell
+## install e2b
+npm install -g @e2b/cli
+## check that it is available
+which e2b 
+```
+
+2. Download our pre-configured Dockerfile:
+[e2b.Dockerfile](https://github.com/MiroMindAI/MiroFlow/blob/main/docs/e2b.Dockerfile).
+
+```shell
+wget https://github.com/MiroMindAI/MiroFlow/blob/main/docs/e2b.Dockerfile
+```
+
+3. Run `e2b template build` command [check official doc here](https://e2b.dev/docs/sdk-reference/cli/v1.0.2/template), use `all_pip_apt_pkg` as the name of template.
+
+```shell
+## build the template with `docker build` locally
+E2B_ACCESS_TOKEN=${your-token}
+e2b template build -c "/root/.jupyter/start-up.sh" -n "all_pip_apt_pkg" -d ./e2b.Dockerfile
+## check that template is built successfully
+E2B_ACCESS_TOKEN=${your-token} e2b template list
+```
+
+For additional information, please see the [E2B Docker documentation](https://e2b.dev/docs/sandbox-template).
+
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -0,0 +1,90 @@
+
+## Workflow Overview
+
+MiroFlow handles user queries through a multi-stage and agentic process designed for flexibility and depth. The workflow is organized as follows:
+
+1. **Intent Recognition & Query Augmentation**  
+   LLMs analyze user input to detect intent and refine the query.
+
+2. **Planning & Task Orchestration**  
+   The main agent drafts an execution plan, invokes tools, and coordinates sub-agents.
+
+3. **Delegation to Sub-Agents**  
+   Specialized agents (e.g., agent-browsing) handle complex or domain-specific tasks. Sub-agents independently plan, act, and execute tool calls as needed.
+
+4. **Tool Access via MCP Servers**  
+   When external capabilities are required, agents leverage specialized tools by connecting to MCP (Model Context Protocol) servers.
+
+5. **Result Synthesis & Output Alignment**  
+   After task completion, a dedicated summary process synthesizes results, ensuring the output is high-quality and aligned with user instructions (or benchmark formats).
+
+## Architecture Components
+
+All core components are located in the `MiroFlow/libs/` directory.
+
+```
+MiroFlow/libs/
+├── miroflow/
+│   └── src/miroflow/
+│       ├── prebuilt/
+│       │   ├── pipeline.py              # Pipeline: coordinates task execution
+│       │   ├── orchestrator.py          # Orchestrator: manages LLM ↔ tool flow
+│       │   └── config/                  # Hydra configs for agents, LLMs, pricing
+│       ├── llm/
+│       │   └── client.py                # Unified LLM client
+│       ├── utils/
+│       │   ├── io_utils.py              # Output formatting utilities
+│       │   ├── prompt_utils.py          # Prompt definitions for agents
+│       │   └── tool_utils.py            # Tool configuration helpers
+│       └── logging/                     # Task logging & metrics
+│
+├── miroflow-tool/
+│   └── src/miroflow/tool/
+│       ├── manager.py                   # Tool Manager: MCP server connector
+│       └── mcp_servers/                 # Individual MCP tool servers
+│           ├── python_server.py         # Code execution
+│           ├── vision_mcp_server.py     # Visual perception
+│           ├── searching_mcp_server.py  # Web search & retrieval
+│           ├── audio_mcp_server.py      # Audio transcription
+│           ├── reasoning_mcp_server.py  # Enhanced reasoning
+│           └── reading_mcp_server.py    # Document processing
+```
+
+![Core Component Architecture](figs/core_component_architecture.png)
+
+### Core System 💻
+
+- **Pipeline** (`./miroflow/src/miroflow/prebuilt/pipeline.py`): Main entry point that creates and manages all components, handles error recovery, and returns final results
+
+- **Orchestrator** (`./miroflow/src/miroflow/prebuilt/orchestrator.py`): Manages multi-turn conversations, parses tool calls, executes tools, and delegates to sub-agents
+
+- **LLM Client** (`./miroflow/src/miroflow/llm/client.py`): Unified interface supporting Anthropic, OpenAI, Google, Qwen, DeepSeek, and local deployments
+
+### Tool Integration 🔧
+
+- **Tool Manager** (`./miroflow-tool/src/miroflow/tool/manager.py`) : Comprehensive MCP server connection manager with tool discovery, persistent connections, and error handling
+
+- **MCP Servers** (`./miroflow-tool/src/miroflow/tool/mcp_servers/`) : Individual tool implementations built on FastMCP. Provides extensive capabilities including:
+  - Code execution and analysis (`./python_server.py`)
+  - Visual perception (`./vision_mcp_server.py`)
+  - Web search and content retrieval (`./searching_mcp_server.py`)
+  - Audio transcription (`./audio_mcp_server.py`)
+  - Enhanced reasoning capabilities (`./reasoning_mcp_server.py`)
+  - Document processing and analysis (`./reading_mcp_server.py`)
+
+### Agent System 👷
+
+**Sub-Agents**  
+Specialized agents designed for specific domains (e.g., `agent-browsing` for web navigation). Each sub-agent maintains dedicated tool sets and custom prompts, allowing the main agent to delegate tasks requiring specialized expertise. Agent definitions are managed through configuration files with prompts and descriptions customized in `./miroflow/src/miroflow/utils/prompt_utils.py` and `tool_utils.py`.
+
+### Support Systems ⚙️
+
+- **Configuration System** (`./miroflow/src/miroflow/prebuilt/config/`) : Hydra-powered YAML configuration for agents, LLMs, benchmarks, and pricing
+
+- **Output Formatter** (`./miroflow/src/miroflow/utils/io_utils.py`) : Intelligent response formatting that adapts to various benchmark requirements
+
+- **Task Logger** (`./miroflow/src/miroflow/logging/`) : Comprehensive logging for agent interactions, tool executions, and performance metrics
+
+### Execution Pipeline Data Flow
+
+![Execution Pipeline Data Flow](figs/execution_pipeline.png)