[pull] main from inclusionAI:main

.github/CODEOWNERS

@@ -0,0 +1,29 @@
+# Default: catch-all
+*                           @garrett4wade
+
+# Core package
+/areal/api/                 @garrett4wade
+/areal/engine/              @rchardx
+/areal/experimental/inference_service        @nuzant
+/areal/infra/               @garrett4wade
+/areal/models/              @rchardx
+/areal/trainer/             @garrett4wade
+
+# Tests & Examples
+/tests/                     @garrett4wade @rchardx @nuzant
+/examples/                  @garrett4wade
+
+# Documentation
+/docs/                      @garrett4wade
+
+# CI/CD & infrastructure
+/.github/                   @garrett4wade @nuzant
+/Dockerfile                 @garrett4wade @fishcrap
+pyproject.toml              @garrett4wade @fishcrap
+pyproject.vllm.toml         @garrett4wade @fishcrap
+uv.lock                     @garrett4wade @fishcrap
+uv.vllm.lock                @garrett4wade @fishcrap
+
+# Governance & community
+GOVERNANCE.md               @garrett4wade
+CONTRIBUTING.md             @garrett4wade

CODE_OF_CONDUCT.md

@@ -0,0 +1,155 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity,
+rights, and contributions of all individuals, regardless of characteristics including
+race, ethnicity, caste, color, age, physical characteristics, neurodiversity,
+disability, sex or gender, gender identity or expression, sexual orientation, language,
+philosophy or religion, national or social origin, socio-economic position, level of
+education, or other status. The same privileges of participation are extended to
+everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's
+expectations for positive behavior. We also understand that our words and actions may be
+interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and
+act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of
+   gathering.
+1. Engaging **kindly and honestly** with others.
+1. Respecting **different viewpoints** and experiences.
+1. **Taking responsibility** for our actions and contributions.
+1. Gracefully giving and accepting **constructive feedback**.
+1. Committing to **repairing harm** when it occurs.
+1. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and
+promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary
+   personal attention after any clear request to stop.
+1. **Character attacks.** Making insulting, demeaning, or pejorative comments directed
+   at a community member or group of people.
+1. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior
+   on the basis of immutable identities or traits.
+1. **Sexualization.** Behaving in a way that would generally be considered
+   inappropriately intimate in the context or purpose of the community.
+1. **Violating confidentiality**. Sharing or acting on someone's personal or private
+   information without their permission.
+1. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward
+   any person or group.
+1. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to
+   be someone else to evade enforcement actions.
+1. **Failing to credit sources.** Not properly crediting the sources of content you
+   contribute.
+1. **Promotional materials**. Sharing marketing or other commercial content in a way
+   that is outside the norms of the community.
+1. **Irresponsible communication.** Failing to responsibly present content which
+   includes, links or describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to
+collaborate. Not every conflict represents a code of conduct violation, and this Code of
+Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and
+minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible
+violation, **send an email to the project maintainer fuwth17@gmail.com**.
+
+Community Moderators take reports of violations seriously and will make every effort to
+respond in a timely manner. They will investigate all reports of code of conduct
+violations, reviewing messages, logs, and recordings, or interviewing witnesses and
+other participants. Community Moderators will keep investigation and enforcement actions
+as transparent as possible while prioritizing safety and confidentiality. In order to
+honor these values, enforcement actions are carried out in private with the involved
+parties, but communicating to the whole community may be part of a mutually agreed upon
+resolution.
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been
+violated, the following enforcement ladder may be used to determine how best to repair
+harm, based on the incident's impact on the individuals involved and the community as a
+whole. Depending on the severity of a violation, lower rungs on the ladder may be
+skipped.
+
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   1. Consequence: A private, written warning from the Community Moderators.
+   1. Repair: Examples of repair include a private written apology, acknowledgement of
+      responsibility, and seeking clarification on expectations.
+1. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a warning,
+      or the first incidence of a more serious violation.
+   1. Consequence: A private, written warning with a time-limited cooldown period
+      designed to underscore the seriousness of the situation and give the community
+      members involved time to process the incident. The cooldown period may be limited
+      to particular communication channels or interactions with particular community
+      members.
+   1. Repair: Examples of repair may include making an apology, using the cooldown
+      period to reflect on actions and impact, and being thoughtful about re-entering
+      community spaces after the period is over.
+1. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have tried
+      to address with warnings, or a single serious violation.
+   1. Consequence: A private written warning with conditions for return from suspension.
+      In general, temporary suspensions give the person being suspended time to reflect
+      upon their behavior and possible corrective actions.
+   1. Repair: Examples of repair include respecting the spirit of the suspension,
+      meeting the specified conditions for return, and being thoughtful about how to
+      reintegrate with the community when the suspension is lifted.
+1. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps on the
+      ladder have failed to resolve, or a violation so serious that the Community
+      Moderators determine there is no way to keep the community safe with this person
+      as a member.
+   1. Consequence: Access to all community spaces, tools, and communication channels is
+      removed. In general, permanent bans should be rarely used, should have strong
+      reasoning behind them, and should only be resorted to if working through other
+      remedies has failed to change the behavior.
+   1. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of
+Community Managers to use their discretion and judgment, in keeping with the best
+interests of our community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an
+individual is officially representing the community in public or other spaces. Examples
+of representing our community include using an official email address, posting via an
+official social media account, or acting as an appointed representative at an online or
+offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently
+available at
+[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed
+under CC BY-SA 4.0. To view a copy of this license, visit
+[https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).
+Translations are provided at
+[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
+Additional enforcement and community guideline resources can be found at
+[https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources).
+The enforcement ladder was inspired by the work of
+[Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

CONTRIBUTING.md

@@ -1,13 +1,15 @@
 # Contributing to AReaL
 
 Thank you for your interest in contributing to AReaL! We welcome contributions from
-everyone, whether you're fixing bugs, improving documentation, adding new features, or
+everyone, whether you're fixing bugs, improving documentations, adding new features, or
 helping with code reviews. This guide will help you get started.
 
+Please review our [Code of Conduct](CODE_OF_CONDUCT.md) before participating and our
+[Governance](GOVERNANCE.md) document to understand how the project is managed.
+
 ## Table of Contents
 
 - [Quick Start](#quick-start)
-- [Ways to Contribute](#ways-to-contribute)
 - [Tips for Using AI-Assisted Coding](#tips-for-using-ai-assisted-coding)
 - [CI/CD](#cicd)
 
@@ -33,7 +35,7 @@ helping with code reviews. This guide will help you get started.
    # Install hooks (includes formatting, linting, and commit message checks)
    pre-commit install --install-hooks
    # Subsequent commits will automatically check your files and commit messages:
-   git commit -a -m 'feat: my change'
+   git commit -a -m 'feat(engine): my change'
    ```
 
 1. **Find an Issue:**
@@ -85,50 +87,8 @@ helping with code reviews. This guide will help you get started.
 
 1. **Submit a Pull Request**
 
-We suggest applying our provided claude command `/create-pr` whenever possible.
-
-## Ways to Contribute
-
-### 🐛 Bug Reports
-
-Found a bug? Please create a
-[bug report](https://github.com/inclusionAI/AReaL/issues/new?template=bug.md) with:
-
-- A clear description of the issue
-- Steps to reproduce
-- Expected vs. actual behavior
-- Environment details (commit ID, hardware, software)
-- Full logs when possible
-
-### ✨ Feature Requests
-
-Have an idea? Submit a
-[feature request](https://github.com/inclusionAI/AReaL/issues/new?template=feature.md)
-with:
-
-- Background and use case
-- Proposed solution or implementation approach
-- Expected benefits to the community
-
-### 📚 Documentation
-
-Documentation improvements are always welcome:
-
-- Fix typos or clarify existing docs
-- Add examples or tutorials
-- Improve API documentation
-- Write blog posts or guides
-
-### 💻 Code Contributions
-
-We accept various types of code contributions:
-
-- Bug fixes
-- New features
-- Performance improvements
-- Algorithm implementations
-- Test coverage improvements
-- Code refactoring
+We suggest applying our provided agent harness command `/create-pr` whenever possible.
+Use that in `claude`, `opencode`, or any other coding agent CLI.
 
 **IMPORTANT**: For new features and code refactoring, please submit a corresponding
 issue or open a draft PR to discuss with the core developers before making any code
@@ -205,8 +165,6 @@ def test_some_multi_gpu_functionality():
 
 ### Image Building
 
-> **NOTE:** The image building CI workflow is experimental and subject to change.
-
 The image building workflow can be triggered manually from any branch by users with
 write permissions to the repository.
 

GOVERNANCE.md

@@ -0,0 +1,65 @@
+# AReaL Project Governance
+
+This document describes how the AReaL project is governed.
+
+## Roles
+
+### Contributors
+
+Anyone who files issues, submits pull requests, or participates in discussions is
+considered a contributor. All contributors are expected to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+### Maintainers
+
+Maintainers have write access to the repository and are responsible for reviewing and
+merging pull requests, triaging issues, and guiding the technical direction of the
+project.
+
+| Name         | Organization              | GitHub        |
+| ------------ | ------------------------- | ------------- |
+| Wei Fu       | IIIS, Tsinghua University | @garrett4wade |
+| Wentai Zhang | AReaL Team, Ant Group     | @rchardx      |
+| Zhiyu Mei    | AReaL Team, Ant Group     | @nuzant       |
+| Xujie Shen   | AReaL Team, Ant Group     | @fishcrap     |
+| Tongkai Yang | AReaL Team, Ant Group     | @fredy12      |
+
+### Lead Maintainer (BDFL)
+
+Wei Fu ([@garrett4wade](https://github.com/garrett4wade)) serves as the lead maintainer.
+The lead maintainer has final authority on technical decisions when maintainers cannot
+reach consensus.
+
+### Community Moderators
+
+The [Code of Conduct](CODE_OF_CONDUCT.md) refers to "Community Moderators" as the
+individuals responsible for enforcement. In this project, community moderators are the
+current maintainers listed above.
+
+## Decision-Making
+
+Decisions are made by consensus among maintainers whenever possible. When consensus
+cannot be reached, the lead maintainer makes the final decision.
+
+Pull request approval policy:
+
+- Bug fixes or minor improvements: approved by at least one maintainer.
+- New features, architectural changes, or API modifications: approved by at least two
+  maintainers or the lead maintainer.
+
+## Becoming a Maintainer
+
+New maintainers are added through nomination by an existing maintainer, followed by
+consensus approval from the current maintainers. There are no strict criteria, but
+candidates are generally expected to have a track record of quality contributions and
+constructive participation in the project.
+
+## Code of Conduct
+
+All participants are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+Violations can be reported to fuwth17@gmail.com.
+
+## Amendments
+
+Changes to this governance document require consensus among maintainers. If consensus
+cannot be reached, the lead maintainer decides.

areal/api/cli_args.py

@@ -1135,6 +1135,33 @@ class TrainEngineConfig:
             "e.g. 'fsdp:d4', 'megatron:d4t2p2', 'archon:d2'. Required."
         },
     )
+
+    # v2 controller options
+    _version: str = field(
+        default="v1",
+        metadata={
+            "help": "Train controller implementation version. Use 'v1' for legacy TrainController, 'v2' for GatewayTrainController.",
+            "choices": ["v1", "v2"],
+        },
+    )
+    admin_api_key: str = field(
+        default="areal-admin-key",
+        metadata={
+            "help": "Admin API key used by gateway/router/data-proxy in controller v2."
+        },
+    )
+    log_level: str = field(
+        default="warning",
+        metadata={"help": "Gateway stack log level for controller v2."},
+    )
+    request_timeout: float = field(
+        default=3600.0,
+        metadata={"help": "Gateway request timeout in seconds for controller v2."},
+    )
+    setup_timeout: float = field(
+        default=3600.0,
+        metadata={"help": "Gateway setup timeout in seconds for controller v2."},
+    )
     scheduling_strategy: SchedulingStrategy = field(
         default_factory=SchedulingStrategy,
         metadata={
@@ -1158,6 +1185,10 @@ def __post_init__(self):
                 "memory_efficient_load is for loading pretrained weights on CPU, "
                 "but init_from_scratch creates a model without loading any weights."
             )
+        if self._version not in ("v1", "v2"):
+            raise ValueError(
+                f"_version must be either 'v1' or 'v2', got '{self._version}'"
+            )
 
 
 @dataclass