revise docs

Author: binary-husky

README.md

@@ -29,7 +29,7 @@ We aim to build a easy-to-learn Agent tuner that unlock more possibilities for a
 - **Easy and Friendly**. AgentJet helps you tune models behind your agent workflows easily, optimizing your agents for top performance with minimal effort.
 - **Rich Tutorial Library**. AgentJet provides a rich library of [examples](https://github.com/modelscope/AgentJet/tree/main/tutorial) as tutorials.
 - **Efficient and Scalable**. AgentJet uses [verl] as the default backbone (`--backbone=verl`). However, we also support [trinity](https://github.com/modelscope/Trinity-RFT/) as alternative backbone, accelerating your tuning process via fully asynchronous RFT.
-- **Flexible and Fast**. AgentJet supports [multi-agent workflows](docs/en/workflow.md) and adopts a context merging technique, accelerating training by 1.5x to 20x when the workflow involves multi-turn (or multi-agent) conversations.
+- **Flexible and Fast**. AgentJet supports [multi-agent workflows](docs/en/workflow.md) and adopts a context merging technique, accelerating training by 1.5x to 10x when the workflow involves multi-turn (or multi-agent) conversations.
 - **Reliability and Reproducibility**. Our team keeps track of framework performance across multiple [tasks + major-git-version + training-backbones](https://benchmark.agent-matrix.com/) (under construction, still gathering data, comming soon).
 
 For advanced researchers, AgentJet also provides high-resolution logging and debugging solutions:
@@ -110,7 +110,7 @@ The internal system orchestrates several specialized modules to handle the compl
 * **Task Rollout**: Bridges LLM engines and manages the Gym environment lifecycle.
 * **Task Runner**: Executes the Agent workflow and calculates rewards.
 * **Model Tuner**: Forwards inference requests from the workflow to the LLM engine.
-* **Context Tracker**: Monitors LLM calls and automatically merges shared-history timelines to improve training efficiency by **3x to 10x**.
+* **Context Tracker**: Monitors LLM calls and automatically merges shared-history timelines to improve training efficiency by **1.5x to 10x**.
 
 
 ---

ajet/workflow.py

@@ -24,7 +24,7 @@ async def execute(self, workflow_task: WorkflowTask, tuner: AjetTuner) -> Workfl
 
 1. Single agent scenario 🤖:
 
-    Simply set `model` argument to `model_tuner` when initializing your agent.
+    Simply set `model` argument to `tuner.as_agentscope_model()` when initializing your agent.
     This is a helpful example when you:
     - 🌟 Know exactly which agents should be trained, or the number of agents are small;
     - ✨ Already finished basic debugging of your workflow using a fixed model such as qwen-max;
@@ -92,17 +92,35 @@ async def execute(self, workflow_task: WorkflowTask, tuner: AjetTuner) -> Workfl
     [ ]   roles = ["werewolf"] * 3 + ["villager"] * 3 + ["seer", "witch", "hunter"]
     [ ]   players = []
     [ ]   for i, role in enumerate(roles):
-    [ ]       default_model_for_good_guys = OpenAIChatModel(model_name="qwen-max", stream=False)
-    [ ]       default_model_for_bad_guys = OpenAIChatModel(model_name="qwen-plus", stream=False)
-    [ ]       chosen_model = default_model_for_good_guys if role != "werewolf" else default_model_for_bad_guys  # 🌟
+    [ ]       debug_model_for_good_guys = OpenAIChatModel(model_name="qwen-max", stream=False)
+    [ ]       debug_model_for_bad_guys = OpenAIChatModel(model_name="qwen-plus", stream=False)
+    [ ]       chosen_model = debug_model_for_good_guys if role != "werewolf" else debug_model_for_bad_guys  # 🌟
     [ ]       players += [ReActAgent(
     [ ]           name=f"Player{i + 1}",
     [ ]           sys_prompt=get_official_agent_prompt(f"Player{i + 1}"),
     [-]           model=chosen_model,
-    [+]           model=model_tuner.register_model(role, default_model=chosen_model),
+    [+]           model=tuner.as_agentscope_model(f"Player{i + 1}", role, debug_model=chosen_model),
     [ ]           formatter=OpenAIMultiAgentFormatter(),
     [ ]       )]
 
 
+[ ]   roles = ["werewolf"] * 3 + ["villager"] * 3 + ["seer", "witch", "hunter"]
+[ ]   players = []
+[ ]   for i, agent_role in enumerate(roles):
+[ ]       if agent_role != "werewolf":
+[ ]           chosen_model_for_current_agent = OpenAIChatModel(model_name="qwen-max", stream=False)
+[ ]       else:
+[ ]           chosen_model_for_current_agent = OpenAIChatModel(model_name="qwen-plus", stream=False)
+[ ]       players += [ReActAgent(
+[ ]           name=f"Player{i + 1}",
+[ ]           sys_prompt=get_official_agent_prompt(f"Player{i + 1}"),
+[ ]           model=agentscope_model,
+[ ]           model=tuner.as_agentscope_model(
+[ ]               agent_name=f"Player{i + 1}",
+[ ]               target_tag=agent_role,                          # 🌟 tag agents with their role
+[ ]               debug_model=chosen_model_for_current_agent      # 🌟 assign a debug model, ONLY used when we are NOT training this agent
+[ ]           )
+[ ]           formatter=OpenAIMultiAgentFormatter(),
+[ ]       )]
 
 """

docs/en/agent_framework_support.md

@@ -0,0 +1,17 @@
+# Supported Agent Frameworks
+
+
+
+
+##
+
+
+
+## AgentScope
+
+
+
+
+
+
+

docs/en/installation.md

@@ -2,19 +2,17 @@
 
 This document provides a step-by-step guide to installing AgentJet.
 
-!!! tip "Latest Version Recommended"
+!!! tip "Latest Version Recommended:"
+
     AgentJet is under active development and iteration. We recommend installing from source to get the latest features and bug fixes.
 
----
 
 ## Prerequisites
 
 | Requirement | Version |
 |-------------|---------|
 | **Python** | 3.10 |
-| **CUDA** | 12.8 or higher |
 
----
 
 ## Install from Source
 
@@ -34,98 +32,83 @@ AgentJet supports multiple backbones. Currently we have `verl` and `trinity` (re
 !!! info "Package Manager"
     We recommend using `uv` to manage your Python environment as it is incredibly fast. See also [`uv` installation document](https://docs.astral.sh/uv/getting-started/installation/).
 
-    If you prefer `conda`, you can also install via conda and pip (simply change `uv pip` to `pip`).
-
-=== "Verl (Recommended)"
+    And of course, if you prefer `conda`, you can also install via conda and pip (simply change `uv pip` to `pip`).
 
-    Install with `verl` training backbone:
+=== "VERL (uv)"
 
     ```bash
+    # Install with `verl` training backbone:
+
     uv venv --python=3.10
     source .venv/bin/activate
-    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ -e .[verl]
-    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ --verbose flash-attn --no-deps --no-build-isolation --no-cache
+    uv pip install -e .[verl]
+
+    #`flash-attn` must be installed after other dependencies
+    uv pip install --verbose flash-attn --no-deps --no-build-isolation --no-cache
     ```
 
     !!! warning "flash-attn Installation"
         `flash-attn` must be installed after other dependencies. To build faster, export `MAX_JOBS=${N_CPU}`, or ensure a healthy connection to GitHub to install pre-compiled wheels.
 
-
-=== "Trinity"
-
-    Install with `trinity` training backbone for fully asynchronous RFT:
+=== "VERL (conda)"
 
     ```bash
-    uv venv --python=3.10
-    source .venv/bin/activate
-    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ -e .[trinity]
-    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ --verbose flash-attn --no-deps --no-build-isolation --no-cache
-    ```
+    # Install with `verl` training backbone:
 
----
+    conda create -n ajet-verl python=3.10
+    conda activate ajet-verl
+    pip install -e .[verl]
 
-## Install via Docker
-
-If you prefer one-click dependency installation, we provide a Docker image to jump start!
+    #`flash-attn` must be installed after other dependencies
+    pip install --verbose flash-attn --no-deps --no-build-isolation --no-cache
+    ```
 
-!!! warning "Prerequisites"
-    Before proceeding, ensure you have **nvidia docker** installed on your system. CUDA is needed inside our docker container, which requires toolkits from Nvidia for GPU support.
+    !!! warning "flash-attn Installation"
+        `flash-attn` must be installed after other dependencies. To build faster, export `MAX_JOBS=${N_CPU}`, or ensure a healthy connection to GitHub to install pre-compiled wheels.
 
-### Setup Nvidia Docker Runtime
 
-Please install nvidia docker runtime on the host Ubuntu system. For details, refer to:
+=== "VERL (aliyun)"
 
-- [Nvidia Official Document](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installing-on-ubuntu-and-debian)
-- [Setup Ubuntu Guide](./setup_ubuntu.md) (our step-by-step manual)
 
-### Run Docker Container
+    ```bash
+    # Install with `verl` training backbone:
 
-This command mounts your current working directory (the root directory of agentjet) to `/workspace` and your data directory to `/data` inside the container.
+    uv venv --python=3.10
+    source .venv/bin/activate
+    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ -e .[verl]
 
-```bash
-docker run -it \
-  --gpus all \
-  --shm-size="64g" \
-  --rm \
-  -v $PWD:/workspace \
-  -v /path/to/your/checkpoint/and/data:/data \
-  agentjet:latest
-```
+    #`flash-attn` must be installed after other dependencies
+    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ --verbose flash-attn --no-deps --no-build-isolation --no-cache
+    ```
 
----
+    !!! warning "flash-attn Installation"
+        `flash-attn` must be installed after other dependencies. To build faster, export `MAX_JOBS=${N_CPU}`, or ensure a healthy connection to GitHub to install pre-compiled wheels.
 
-## Verify Installation
 
-After installation, verify that everything is working correctly:
+=== "Trinity"
 
-```python
-import ajet
-print(ajet.__version__)
-```
+    ```bash
+    # Install with `trinity` training backbone for fully asynchronous RFT:
 
----
+    uv venv --python=3.10
+    source .venv/bin/activate
+    uv pip install -e .[trinity]
+    uv pip install --verbose flash-attn --no-deps --no-build-isolation --no-cache
+    ```
 
-## Troubleshooting
 
-??? note "Common Issues"
-    **Issue**: `flash-attn` installation fails
+=== "Trinity (aliyun)"
 
-    **Solution**: Make sure you have CUDA toolkit installed and `MAX_JOBS` environment variable set:
     ```bash
-    export MAX_JOBS=4
-    uv pip install flash-attn --no-build-isolation
-    ```
+    # Install with `trinity` training backbone for fully asynchronous RFT:
 
-??? note "GPU Not Detected"
-    **Issue**: Docker container doesn't see GPU
-
-    **Solution**: Ensure nvidia-docker is properly installed:
-    ```bash
-    nvidia-smi  # Should show GPU info
-    docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
+    uv venv --python=3.10
+    source .venv/bin/activate
+    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ -e .[trinity]
+    uv pip install -i https://mirrors.aliyun.com/pypi/simple/ --verbose flash-attn --no-deps --no-build-isolation --no-cache
     ```
 
----
+
 
 ## Next Steps
 

docs/en/intro.md

@@ -1,37 +1,28 @@
 # Introduction
 
-**AgentJet (AgentJet)** is a cutting-edge, user-friendly training framework designed to optimize AgentScope agents and workflows, fine-tuning language model weights behind the scenes.
+**AgentJet (AgentJet)** is a cutting-edge, user-friendly agent tunning framework designed to optimize LLM models and agent workflows.
 
-Simply provide your AgentScope workflow, training data, and reward function, and we will be ready to enhance your agents to their optimal performance!
+Simply provide your workflow (built from AgentScope, OpenAI SDK, Langchain, raw HTTP requests, or hybrid of all of them), training data, and reward function, and we will be ready to enhance your agents to their optimal performance!
 
----
 
 ## Features
 
-We aim to build an easy-to-learn AgentJet that unlocks more possibilities for agent developers:
-
-<div class="card-grid">
-<a href="./configuration/" class="feature-card"><div class="card-header"><img src="https://api.iconify.design/lucide:rocket.svg" class="card-icon card-icon-agent" alt=""><h3>Easy and Friendly</h3></div><p class="card-desc">AgentJet helps you tune models behind your agent workflows easily, optimizing your agents for top performance with minimal effort.</p></a>
-<a href="#example-library" class="feature-card"><div class="card-header"><img src="https://api.iconify.design/lucide:book-open.svg" class="card-icon card-icon-general" alt=""><h3>Rich Tutorial Library</h3></div><p class="card-desc">Rich library of examples as tutorials: Math Agent, Werewolves Game, AppWorld and more.</p></a>
-<a href="./installation/" class="feature-card"><div class="card-header"><img src="https://api.iconify.design/lucide:zap.svg" class="card-icon card-icon-tool" alt=""><h3>Efficient and Scalable</h3></div><p class="card-desc">Uses <a href="https://github.com/modelscope/Trinity-RFT/">Trinity</a> as the default backbone with fully asynchronous RFT. Support for verl backbone as fallback.</p></a>
-</div>
+AgentJet aims to build a state-of-the-art agent tuning platform for both developers and researchers
 
-!!! tip "Multi-Agent Support"
-    AgentJet supports [multi-agent workflows](./workflow.md) and adopts a context merging technique, accelerating training by **1.5x to 20x** when the workflow involves multi-turn (or multi-agent) conversations.
+- **Easy and Friendly**. AgentJet helps you tune models behind your agent workflows easily, optimizing your agents for top performance with minimal effort.
+- **Rich Tutorial Library**. AgentJet provides a rich library of [examples](https://github.com/modelscope/AgentJet/tree/main/tutorial) as tutorials.
+- **Efficient and Scalable**. AgentJet uses [verl] as the default backbone (`--backbone=verl`). However, we also support [trinity](https://github.com/modelscope/Trinity-RFT/) as alternative backbone, accelerating your tuning process via fully asynchronous RFT.
+- **Flexible and Fast**. AgentJet supports [multi-agent workflows](docs/en/workflow.md) and adopts a context merging technique, accelerating training by 1.5x to 10x when the workflow involves multi-turn (or multi-agent) conversations.
+- **Reliability and Reproducibility**. Our team keeps track of framework performance across multiple [tasks + major-git-version + training-backbones](https://benchmark.agent-matrix.com/) (under construction, still gathering data, comming soon).
 
-!!! info "Reliability & Reproducibility"
-    Our team keeps track of framework performance across multiple [tasks + major-git-version + training-backbones](https://benchmark.agent-matrix.com/).
+For advanced researchers, AgentJet also provides high-resolution logging and debugging solutions:
+<!-- For advanced researchers, AgentJet provides high-resolution logging and debugging solutions that are, to our knowledge, unprecedented in other prior projects. -->
 
-### For Advanced Researchers
+- **High-Resolution Logging**: AgentJet allows users to save and inspect token-level rollout details, recording token IDs, token loss masks, and even token logprobs to facilitate workflow development and agent diagnostics.
+- **Fast Debugging**: AgentJet also provides the `--backbone=debug` option for the best debugging experience, shortening your wait period from minutes to seconds after code changes and enabling breakpoint debugging in IDEs.
 
-AgentJet also provides high-resolution logging and debugging solutions:
 
-| Feature | Description |
-|---------|-------------|
-| **High-Resolution Logging** | Save and inspect token-level rollout details, recording token IDs, token loss masks, and even token logprobs |
-| **Fast Debugging** | Use `--backbone=debug` option, shortening wait time from minutes to seconds after code changes |
 
----
 
 ## Quick Start
 
@@ -52,10 +43,10 @@ We recommend using `uv` for dependency management.
     uv venv --python=3.10.16 && source .venv/bin/activate
     uv pip install -e .[trinity]
     # Note: flash-attn must be installed after other dependencies
-    uv pip install flash_attn==2.8.1 --no-build-isolation --no-cache-dir
+    uv pip install flash_attn==2.8.3 --no-build-isolation --no-cache-dir
     ```
 
-### Run Training
+- Train the first agent
 
 You can start training your first agent with a single command using a pre-configured YAML file:
 
@@ -66,7 +57,6 @@ ajet --conf tutorial/example_math_agent/math_agent.yaml --backbone='trinity' --w
 !!! example "Learn More"
     See the [Math Agent](./example_math_agent.md) example for detailed explanation.
 
----
 
 ## Example Library {#example-library}
 
@@ -112,7 +102,7 @@ The internal system orchestrates several specialized modules to handle the compl
 | **Task Rollout** | Bridges LLM engines and manages the Gym environment lifecycle |
 | **Task Runner** | Executes the AgentScope workflow and calculates rewards |
 | **Model Tuner** | Forwards inference requests from the workflow to the LLM engine |
-| **Context Tracker** | Monitors LLM calls and automatically merges shared-history timelines (**3x-10x** efficiency boost) |
+| **Context Tracker** | Monitors LLM calls and automatically merges shared-history timelines (**1.5x-10x** efficiency boost) |
 
 ---
 

docs/en/introduction.md

@@ -13,7 +13,7 @@ We aim to build a easy-to-learn AgentJet that unlock more possibilities for agen
 - **Easy and Friendly**. AgentJet helps you tune models behind your agent workflows easily, optimizing your agents for top performance with minimal effort.
 - **Rich Tutorial Library**. AgentJet provides a rich library of [examples](#example-library) as tutorials.
 - **Efficient and Scalable**. AgentJet uses [trinity](https://github.com/modelscope/Trinity-RFT/) as the default backbone (`--backbone=trinity`), accelerating your tuning process via fully asynchronous RFT. Nevertheless, if actor colocating is your preference, you can still fall back to the [verl](./installation.md) backbone.
-- **Flexible and Fast**. AgentJet supports [multi-agent workflows](./workflow.md) and adopts a context merging technique, accelerating training by 1.5x to 20x when the workflow involves multi-turn (or multi-agent) conversations.
+- **Flexible and Fast**. AgentJet supports [multi-agent workflows](./workflow.md) and adopts a context merging technique, accelerating training by 1.5x to 10x when the workflow involves multi-turn (or multi-agent) conversations.
 - **Reliability and Reproducibility**. Our team keeps track of framework performance across multiple [tasks + major-git-version + training-backbones](https://benchmark.agent-matrix.com/) (under construction, still gathering data, comming soon).
 
 For advanced researchers, AgentJet also provides high-resolution logging and debugging solutions:
@@ -94,7 +94,7 @@ The internal system orchestrates several specialized modules to handle the compl
 * **Task Rollout**: Bridges LLM engines and manages the Gym environment lifecycle.
 * **Task Runner**: Executes the AgentScope workflow and calculates rewards.
 * **Model Tuner**: Forwards inference requests from the workflow to the LLM engine.
-* **Context Tracker**: Monitors LLM calls and automatically merges shared-history timelines to improve training efficiency by **3x to 10x**.
+* **Context Tracker**: Monitors LLM calls and automatically merges shared-history timelines to improve training efficiency by **1.5x to 10x**.
 
 
 ---