From c1792e77b8d3fe556a2135531433c7b7b5a5d675 Mon Sep 17 00:00:00 2001 From: bluemoon-o2 <2095774200@qq.com> Date: Mon, 3 Aug 2026 20:06:48 +0800 Subject: [PATCH 1/4] docs(git): document dedicated Xet transfers --- docs/hub/authentication.md | 9 +++++---- docs/hub/repositories.md | 10 ++++++---- docs/megatensors/guides/cli.md | 9 ++++++--- hub/authentication.md | 11 ++++++----- hub/repositories.md | 10 ++++++---- hub/security.md | 5 ++++- xet/git-lfs-compatibility.md | 8 +++++++- xet/using-xet-storage.md | 17 ++++++++++++++++- 8 files changed, 56 insertions(+), 23 deletions(-) diff --git a/docs/hub/authentication.md b/docs/hub/authentication.md index df4144f..a392791 100644 --- a/docs/hub/authentication.md +++ b/docs/hub/authentication.md @@ -99,9 +99,10 @@ Account-key operations require `account:keys` when called with a fine-grained to Generate a dedicated Ed25519 key, upload only its public half, and verify the host greeting: -> **The Web/API and SSH hostnames are intentionally different.** Use -> `mega.tensorplay.cn` for the website, API, and HTTPS Git, but use -> `ssh.tensorplay.cn` for SSH Git. Do not substitute one hostname for the other. +> **HTTPS and SSH use different published hostnames.** Use +> `git.tensorplay.cn` directly for HTTPS Git and `ssh.tensorplay.cn` for SSH. +> Existing Git remotes on `mega.tensorplay.cn` remain compatible through a +> streamed fallback; use the dedicated HTTPS host for new clones. ```bash ssh-keygen -t ed25519 -C "$USER@$(hostname)" -f ~/.ssh/id_ed25519_mega @@ -115,7 +116,7 @@ Host ssh.tensorplay.cn EOF ssh -T git@ssh.tensorplay.cn -git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY.git +git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY ``` The SSH key authenticates the account; normal repository permissions still decide read or write access. Removing the key immediately prevents new SSH authorization. diff --git a/docs/hub/repositories.md b/docs/hub/repositories.md index 25fd92b..7ab5b6e 100644 --- a/docs/hub/repositories.md +++ b/docs/hub/repositories.md @@ -19,12 +19,14 @@ Repository type is selected at creation and is one of `model`, `dataset`, or `sp HTTPS works for public clone and bearer-backed credential helpers; SSH is the recommended interactive write transport after registering a public key: -> The domains are different by design: use `mega.tensorplay.cn` for Web/API and -> HTTPS Git, and `ssh.tensorplay.cn` for SSH Git. +> Use `git.tensorplay.cn` directly for HTTPS Git and `ssh.tensorplay.cn` for SSH. +> Existing `mega.tensorplay.cn` Git remotes remain compatible through a streamed +> fallback, but new clones should use the dedicated Git data plane for performance. ```bash -git clone https://mega.tensorplay.cn/mega/qwen-release.git -git clone git@ssh.tensorplay.cn:mega/qwen-release.git +curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh +git clone https://git.tensorplay.cn/mega/qwen-release.git +git clone git@ssh.tensorplay.cn:mega/qwen-release cd qwen-release git add . diff --git a/docs/megatensors/guides/cli.md b/docs/megatensors/guides/cli.md index 03d7f00..3c1dac2 100644 --- a/docs/megatensors/guides/cli.md +++ b/docs/megatensors/guides/cli.md @@ -147,14 +147,17 @@ The create command reveals a generated signing secret once. See [Webhooks](/docs ## Git, SSH, and GPG smoke test -MEGA uses different public hosts: Web/API and HTTPS Git use -`mega.tensorplay.cn`, while SSH Git uses `ssh.tensorplay.cn`. +MEGA publishes Web/API URLs on `mega.tensorplay.cn`, HTTPS Git directly on +`git.tensorplay.cn`, and SSH Git on `ssh.tensorplay.cn`. Existing Hub-host Git +remotes continue to work through a streamed compatibility fallback. ```bash ssh-keygen -t ed25519 -C "$USER@$(hostname)" -f ~/.ssh/id_ed25519_mega mega auth keys add ~/.ssh/id_ed25519_mega.pub --name workstation +curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh +git clone https://git.tensorplay.cn/OWNER/REPOSITORY.git ssh -T -i ~/.ssh/id_ed25519_mega git@ssh.tensorplay.cn -git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY.git +git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY ``` Register and exercise a signing key whose email matches the MEGA account: diff --git a/hub/authentication.md b/hub/authentication.md index 9b56575..c564620 100644 --- a/hub/authentication.md +++ b/hub/authentication.md @@ -102,9 +102,10 @@ Account-key operations require `account:keys` when called with a fine-grained to Generate a dedicated Ed25519 key, upload only its public half, and verify the host greeting: -> **The Web/API and SSH hostnames are intentionally different.** Use -> `mega.tensorplay.cn` for the website, API, and HTTPS Git, but use -> `ssh.tensorplay.cn` for SSH Git. Do not substitute one hostname for the other. +> **HTTPS and SSH use different published hostnames.** Use +> `git.tensorplay.cn` directly for HTTPS Git and `ssh.tensorplay.cn` for SSH. +> Existing Git remotes on `mega.tensorplay.cn` remain compatible through a +> streamed fallback; use the dedicated HTTPS host for new clones. ```bash ssh-keygen -t ed25519 -C "$USER@$(hostname)" -f ~/.ssh/id_ed25519_mega @@ -118,7 +119,7 @@ Host ssh.tensorplay.cn EOF ssh -T git@ssh.tensorplay.cn -git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY.git +git clone git@ssh.tensorplay.cn:OWNER/REPOSITORY ``` The SSH key authenticates the account; normal repository permissions still decide read or write access. Removing the key immediately prevents new SSH authorization. @@ -139,7 +140,7 @@ ssh-keyscan -t ed25519 ssh.tensorplay.cn 2>/dev/null | ssh-keygen -lf - ``` If `ssh -T` cannot connect, use HTTPS Git while the issue is investigated. -Successful HTTPS access on `mega.tensorplay.cn` does not prove SSH reachability +Successful HTTPS access on `git.tensorplay.cn` does not prove SSH reachability on `ssh.tensorplay.cn`. ## GPG commit verification diff --git a/hub/repositories.md b/hub/repositories.md index 72b6dad..ec03a49 100644 --- a/hub/repositories.md +++ b/hub/repositories.md @@ -36,12 +36,14 @@ Use the type-specific guides for recommended layouts and publication checks: HTTPS works for public clone and bearer-backed credential helpers; SSH is the recommended interactive write transport after registering a public key: -> The domains are different by design: use `mega.tensorplay.cn` for Web/API and -> HTTPS Git, and `ssh.tensorplay.cn` for SSH Git. +> Use `git.tensorplay.cn` directly for HTTPS Git and `ssh.tensorplay.cn` for SSH. +> Existing `mega.tensorplay.cn` Git remotes remain compatible through a streamed +> fallback, but new clones should use the dedicated Git data plane for performance. ```bash -git clone https://mega.tensorplay.cn/mega/qwen-release.git -git clone git@ssh.tensorplay.cn:mega/qwen-release.git +curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh +git clone https://git.tensorplay.cn/mega/qwen-release.git +git clone git@ssh.tensorplay.cn:mega/qwen-release cd qwen-release git add . diff --git a/hub/security.md b/hub/security.md index 05e7a13..5bde460 100644 --- a/hub/security.md +++ b/hub/security.md @@ -41,7 +41,10 @@ Revoke a credential when its purpose ends, its storage boundary changes, or it m ## Secure Git access -Use `ssh.tensorplay.cn` for SSH Git and `mega.tensorplay.cn` for Web, API, and HTTPS Git. Upload only the `.pub` half of an SSH key: +Use the dedicated `git.tensorplay.cn` data plane for HTTPS Git and +`ssh.tensorplay.cn` for SSH Git. Existing `mega.tensorplay.cn` Git remotes +remain compatible through a streamed fallback. Upload only the `.pub` half of +an SSH key: ```bash ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_mega diff --git a/xet/git-lfs-compatibility.md b/xet/git-lfs-compatibility.md index 10e99d3..3bee728 100644 --- a/xet/git-lfs-compatibility.md +++ b/xet/git-lfs-compatibility.md @@ -10,7 +10,8 @@ storage protocol. Clone the repository, make your change, commit it, and push as usual: ```bash -git clone https://mega.tensorplay.cn/OWNER/REPOSITORY.git +curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh +git clone https://git.tensorplay.cn/OWNER/REPOSITORY.git cd REPOSITORY git add . git commit -m "Update weights" @@ -21,6 +22,11 @@ The repository remains the source of truth for its visible files, history, and revisions. Use the [MEGA CLI](/docs/megatensors/guides/cli) when a large release tree needs resumable transfer or a scripted workflow. +MEGA's Git-Xet client advertises `xet` for upload and `xet-download` for +download. Once the Git LFS batch request is authorized, Git-Xet sends and +receives file bytes directly from the negotiated Xet CAS. The Hub and Git +Gateway stay on the control plane and do not proxy the large-file stream. + ## Migrate gradually Keep using the Git and Git LFS tooling that your project already requires. diff --git a/xet/using-xet-storage.md b/xet/using-xet-storage.md index 7de5d9d..73f48c6 100644 --- a/xet/using-xet-storage.md +++ b/xet/using-xet-storage.md @@ -4,6 +4,21 @@ Use Xet through MEGA's ordinary repository tools. For most workflows, select a repository, keep the source tree stable while it transfers, and use a commit or tag when the release is ready. +## Install Git-Xet + +Install MEGA's Git-Xet build from the stable installer endpoint: + +```bash +curl -sSfL https://mega.tensorplay.cn/git-xet/install.sh | sh +git xet --version +``` + +The installer registers `xet` for uploads and `xet-download` for downloads. +Both operations transfer large-file bytes directly between Git-Xet and the Xet +CAS returned by MEGA; the Hub and Git Gateway only negotiate scoped actions and +tokens. Older Git-Xet clients remain compatible and use the signed basic +download path when they do not advertise `xet-download`. + ## Upload a large release tree Use the resumable uploader for large directories: @@ -33,7 +48,7 @@ files or small changes, use the repository commands in Standard Git repository workflows continue to work for MEGA repositories: ```bash -git clone https://mega.tensorplay.cn/OWNER/REPOSITORY.git +git clone https://git.tensorplay.cn/OWNER/REPOSITORY.git cd REPOSITORY git add . git commit -m "Publish release" From c2bd0bafafa03eb6e777663b9949696d72728401 Mon Sep 17 00:00:00 2001 From: bluemoon-o2 <2095774200@qq.com> Date: Tue, 4 Aug 2026 23:45:26 +0800 Subject: [PATCH 2/4] docs: update Hub product guides --- docs/megatensors/package_reference/format.md | 34 +++++ hub/datasets-data-files.md | 35 +++++ hub/datasets-data-studio.md | 4 +- hub/datasets-sql-console.md | 14 +- hub/datasets-viewer.md | 41 ++++- hub/discussions.md | 7 + hub/hugging-face-compatibility.md | 11 +- hub/model-evaluations.md | 149 +++++++++++++++---- hub/model-widgets.md | 50 ++++++- hub/models.md | 13 ++ hub/notifications.md | 8 +- 11 files changed, 316 insertions(+), 50 deletions(-) diff --git a/docs/megatensors/package_reference/format.md b/docs/megatensors/package_reference/format.md index 5159671..95f2431 100644 --- a/docs/megatensors/package_reference/format.md +++ b/docs/megatensors/package_reference/format.md @@ -78,6 +78,40 @@ The index records shard files and tensor placement: Runtime APIs resolve the index first, then open only the shards required by the requested tensors. +## Hub repository metadata card + +Model repository pages summarize MEGA-native artifacts in a **MegaTensors** +metadata card. The card inspects artifact data at the selected revision; it does +not infer tensor counts or dtypes from the model name. + +The inspection entry point is deterministic: + +- A release with one `.mega` file inspects that file directly. +- A release with multiple `.mega` shards inspects the first + `.mega.index.json` path in lexical order. +- A multi-shard release without an index remains identifiable as MEGA, but the + page cannot validate aggregate tensor metadata. + +The rendered fields use these sources and fallbacks: + +| Card field | Artifact source | Fallback | +| --- | --- | --- | +| Model size | `summary.parameter_count` from a directly inspected `.mega` file | A parameter-size token in repository identity or tags; otherwise stored size | +| Tensor type | Dtype counts in the inspected artifact, ordered by tensor count | A precision token in repository identity or tags; otherwise `Mixed` | +| Tensors | `summary.tensor_count` | Hidden when detailed inspection is unavailable | +| Files info | One file for a single artifact, or `summary.shard_count` for an index | Number of selected weight artifacts | +| Verified | Successful bounded artifact inspection | Hidden when inspection has not completed or failed | + +Here **Verified** means that the Hub parsed and validated the artifact header or +index contract. It does not assert publisher identity, model quality, or +benchmark correctness. Use [Signing and Trust](/docs/hub/trust) for publisher +provenance and [Model Evaluations](/docs/hub/model-evaluations) for benchmark +evidence. + +The card's **Files info** control opens the inspected artifact when there is a +stable file target. Otherwise it opens the selected repository tree so readers +can inspect the release layout themselves. + ## Integrity MEGA stores hashes for payload verification: diff --git a/hub/datasets-data-files.md b/hub/datasets-data-files.md index f1e3786..b03193d 100644 --- a/hub/datasets-data-files.md +++ b/hub/datasets-data-files.md @@ -17,5 +17,40 @@ The names are your contract: document every split, format, compression method, field type, and identifier policy in the card. Publish checksums for important exports and create a new revision when the meaning of an existing split changes. +Dataset Viewer can infer conventional `train`, `validation`, and `test` file +names automatically. For more than one configuration, nonstandard names, or a +custom delimiter, declare the mapping in the dataset card front matter: + +```yaml +--- +configs: + - config_name: english + default: true + data_dir: data/en + data_files: + - split: train + path: + - train-*.jsonl.gz + - split: validation + path: validation.jsonl.gz + - config_name: french + data_files: + train: data/fr/train.csv + test: data/fr/test.csv + delimiter: "," + encoding: utf-8 +--- +``` + +`data_files` accepts a string, a list, split-to-path mappings, path lists, and +repository-relative globs. A `data_dir` is prepended to paths within that +configuration. Keep configuration and split names stable because compatible +Viewer and Parquet URLs include both values. + +For image, audio, video, PDF, or WebDataset archives, keep file extensions and +archive member names meaningful. The Viewer preserves semantic media features +and exposes member paths in previews; the original binary data remains in the +derived Parquet representation. + Do not put access tokens, raw credentials, or unreviewed personal data in data files or examples. diff --git a/hub/datasets-data-studio.md b/hub/datasets-data-studio.md index b7a8aaa..f956c60 100644 --- a/hub/datasets-data-studio.md +++ b/hub/datasets-data-studio.md @@ -8,8 +8,10 @@ the Data Studio Agent for a selected configuration and split. Use Data Studio to answer practical questions about a dataset revision: -- inspect its schema, sample rows, and column statistics in Dataset Viewer; +- inspect paginated rows, search and filter the indexed split, and open a + durable row link in Dataset Viewer; - use SQL Console for a read-only filter, aggregation, or quality check; +- share or embed SQL and download a result as CSV or Parquet; - save a useful query for your own later review; - ask the Data Studio Agent to explain the selected schema, preview values, data-quality questions, or suggest a SQL query. diff --git a/hub/datasets-sql-console.md b/hub/datasets-sql-console.md index d26c982..5e30677 100644 --- a/hub/datasets-sql-console.md +++ b/hub/datasets-sql-console.md @@ -20,10 +20,16 @@ ORDER BY examples DESC LIMIT 20 ``` -Queries must be a single `SELECT` statement over the selected `data` view. -The console does not permit writes, file access, or changes to the repository. -Keep result sets focused with `LIMIT`, and use the Viewer to inspect individual -rows and column statistics. +Queries run locally in the browser and must be one read-only +`SELECT` statement or common-table expression over the selected `data` view. +The console does not permit writes, external file readers, or changes to the +repository. Keep result sets focused with `LIMIT`, and use the Viewer to inspect +individual rows and column statistics. + +After a query finishes, you can share a URL that restores the SQL, copy an +iframe embed, download the result as CSV or Parquet, or copy an equivalent +`mega datasets sql` command. These exports contain the returned result rows; +they do not alter the dataset revision. ## Save a personal query diff --git a/hub/datasets-viewer.md b/hub/datasets-viewer.md index 6196fe2..93f1dfe 100644 --- a/hub/datasets-viewer.md +++ b/hub/datasets-viewer.md @@ -4,19 +4,56 @@ Dataset Viewer is the browser preview in a dataset repository's **Data Studio** tab. It lets readers inspect indexed dataset configurations and splits without downloading the full repository. +## Automatic conversion + +When a supported dataset revision is published, MEGA automatically prepares a +Parquet view for Data Studio. The source files are unchanged, and readers can +continue to download the exact published revision. + +The converter recognizes CSV, TSV, JSON, JSON Lines, NDJSON, Parquet, Arrow, +Feather, plain text, common image/audio/video files, PDF, ZIP, TAR, and +WebDataset-style TAR archives. Tabular files may also use `gz`, `bz2`, `xz`, +`zst`, or `zstd` compression. A dataset card can select files with Hugging Face +`configs`, `data_files`, `data_dir`, path lists and globs, `default: true`, +`delimiter` or `sep`, and `encoding` fields. Without an explicit configuration, +MEGA infers `train`, `validation`, and `test` from file names and uses `train` +for remaining files. + +Large or partially supported datasets may expose an indexed subset. Data Studio +labels that view as `partial` so readers do not mistake it for the complete +source dataset. Set `viewer: false` in the dataset card front matter when a +repository should not prepare a Viewer. + ## Open a split Open a dataset repository and select **Data Studio**. Choose a configuration and split to view: -- a schema-aware preview of the first rows; +- pages of up to 100 rows across the indexed Parquet split; - the selected split's row count, file size, and column count when available; -- per-column type, value count, and null count. +- full-split text search, column distribution filters, and row deep links; +- per-column type, value count, null count, and interactive distributions; +- inline image, audio, video, and structured agent-trace cells when present. The Viewer respects repository visibility. A private dataset can be explored only by people who can read that dataset, and a Viewer session always reflects the dataset revision currently published by the repository. +When the Viewer reports a partial dataset, its search, filters, pages, and SQL +queries cover only the indexed Parquet subset. Check the repository files and +dataset card before treating that subset as the full source dataset. + +Search, filters, pagination, and SQL cover the indexed Parquet view of the +selected split. They do not alter the published dataset revision. + +## Compatible access + +Compatible clients can read split metadata, first rows, schema, sizes, +statistics, Croissant metadata, and generated Parquet URLs through the Hub API. +Parquet downloads support partial requests and follow the same public/private +permissions as the dataset. See the live [OpenAPI Explorer](/spaces/mega/openapi) +for the current request and response schemas. + ## When a preview is not ready Data Studio prepares views for supported dataset revisions before it can show a diff --git a/hub/discussions.md b/hub/discussions.md index 9eec716..7ebc169 100644 --- a/hub/discussions.md +++ b/hub/discussions.md @@ -77,6 +77,13 @@ The proposal records the source and target revisions at creation. The CLI identi ## Review and merge +In the browser, open **Community → Pull requests**, select a proposal, review its +commits and file diff, and use the thread for review comments. Personal owners, +or organization members with `admin` or `write` access, receive an Inbox review +request when another account opens a PR. If discussion-activity email is enabled +in notification settings, MEGA also queues a dedicated **Pull Request review +requested** email whose **Review Pull Request** action links to the same review. + Inspect the commits and file changes carried by a proposal: ```bash diff --git a/hub/hugging-face-compatibility.md b/hub/hugging-face-compatibility.md index af6cd17..d7e2187 100644 --- a/hub/hugging-face-compatibility.md +++ b/hub/hugging-face-compatibility.md @@ -36,7 +36,7 @@ the Hugging Face client ecosystem: | File upload and download | `hf upload`, `hf download`, `upload_folder`, and `snapshot_download` | `mega upload`, `mega download`, and `mega snapshot` | | Branches, tags, copy, and visibility | `hf repos` and `HfApi` repository methods | `mega repos branch`, `mega repos tag`, and `mega repos settings` | | Model loading | Transformers and other libraries built on `huggingface_hub` | `megatensors` for `.mega` artifacts | -| Dataset loading | Datasets and other libraries built on `huggingface_hub` | `mega snapshot` or resolver URLs | +| Dataset loading and derived Parquet | Datasets, Dataset Viewer metadata, `/api/datasets/{id}/parquet`, and range-capable Parquet shards | Data Studio, `mega snapshot`, or resolver URLs | | Mutable working data | `hf buckets` and compatible Bucket APIs | `mega buckets` and `mega://buckets/...` | Compatibility changes the transport and repository endpoint. It does not turn @@ -128,9 +128,12 @@ Repository-card metadata is parsed in the Hugging Face YAML format. MEGA does not emulate every Hugging Face product. The `hf` compatibility write endpoint does not accept implicit pull-request commits; use native `mega upload --create-pr`, which creates a branch, performs the atomic upload, then opens a -native pull request. Dataset viewing and SQL exploration -are provided in MEGA's [Data Studio](/docs/hub/datasets-data-studio), rather -than through Hugging Face Dataset Viewer conversion APIs. Bucket S3 access and +native pull request. Dataset revisions are automatically converted for MEGA's +[Data Studio](/docs/hub/datasets-data-studio), and compatible clients can read +the generated Parquet map, shards, first rows, schema, size, statistics, and +Croissant metadata. Server-side Dataset Viewer `rows`, `search`, and `filter` +are not emulated; Data Studio provides interactive browsing over the indexed +Parquet view instead. Bucket S3 access and managed Space volumes are available through MEGA's native public interfaces; see [Bucket S3 Gateway](/docs/hub/storage-buckets-s3) and [Space Storage](/docs/hub/spaces-storage). Use [Hub API](/docs/hub/api) and diff --git a/hub/model-evaluations.md b/hub/model-evaluations.md index df13cde..70378c2 100644 --- a/hub/model-evaluations.md +++ b/hub/model-evaluations.md @@ -1,49 +1,134 @@ # Model Evaluations -Model evaluations attach structured test results to a model repository so -readers can inspect the task, metric, score, and source alongside the release. -They complement a [Repository Card](/docs/hub/repository-cards); they do not -replace an explanation of the data, method, limitations, or intended use. +Model repositories can publish structured benchmark results from +HF-compatible `.eval_results/*.yaml` files. The model page reads files merged +into `main` as repository results and also shows results proposed by open Pull +Requests with a **community** label. -## Add useful results +## Submit a benchmark score -For each result, record a recognizable evaluation suite, task, metric, score, -and unit. Add a source URL or concise details when they help a reader reproduce -or interpret the result. Link the result to the release revision it describes -in the card or source material. +1. Open the model page and find **Evaluation results**. +2. Select **Submit results** and sign in. +3. Enter the dataset ID, task ID, numeric score, and any reproducibility fields. +4. Select **Open Pull Request**. +5. Review the generated Pull Request from the model repository's **Community** tab. -Do not compare scores unless the task, dataset version, split, preprocessing, -prompting, hardware assumptions, and metric definition are compatible. State -known limitations, confidence intervals, and failure cases in the model card. +The browser creates a dedicated contribution branch, writes one YAML file below +`.eval_results/`, and opens a Pull Request against `main`. A contributor does +not need repository write permission for this scoped flow, but the repository +must be readable and its Community feature must be enabled. The contribution is +attributed to the signed-in account. -## Read results on a model page +While the Pull Request is open, its new or changed evaluation files appear on +the model page with a **community** label and a link back to the review. Closing +the Pull Request removes those proposed results. Merging it publishes the YAML +on `main`, removes the community label, and makes the result part of repository +history. -Published model pages show their available test results in the evaluation -panel. A result can include a source link and a verification indicator when it -has been reviewed through the applicable MEGA workflow. An absent indicator is -not evidence that a result is incorrect; it means readers should assess the -provided evidence themselves. +## YAML format -## Manage results through the API +Every `.eval_results/*.yaml` file contains a non-empty list. The required fields +match the Hugging Face +[Eval Results specification](https://huggingface.co/docs/hub/eval-results): -Repository writers can manage evaluations with the public Hub API: +```yaml +- dataset: + id: cais/hle + task_id: text-generation + revision: main + value: 56 + date: 2026-08-03 + source: + url: https://example.com/evals/alice-qwen-demo-hle + name: Release evaluation report + user: alice + notes: Revision v1.0, no tools +``` + +| Field | Required | Meaning | +| --- | --- | --- | +| `dataset.id` | Yes | Benchmark dataset in `owner/name` form. | +| `dataset.task_id` | Yes | Task or sub-leaderboard identity. | +| `value` | Yes | Finite numeric result. | +| `dataset.revision` | No | Dataset branch, tag, or commit used for the run. | +| `date` | No | ISO-8601 evaluation date. | +| `source.url` | No | HTTP or HTTPS leaderboard, report, trace, or paper. | +| `source.name` | No | Human-readable evidence source. Requires `source.url`. | +| `source.user` | No | Evaluator or source account. Requires `source.url`. | +| `notes` | No | Concise protocol and reproducibility notes. | + +MEGA never treats a foreign `verifyToken` as a MEGA verification. Verification +badges remain server-managed trust signals. + +## Owner review and notifications + +Open **Community → Pull requests**, select the result PR, inspect its commit and +file diff, and check the benchmark protocol and evidence. A repository writer +can comment, close or reopen the proposal, and merge it when the source remains +a fast-forward descendant of `main`. + +When a contributor opens a PR, MEGA sends an Inbox review request to the +personal repository owner. For organization repositories, organization members +with `admin` or `write` access receive it. MEGA also queues the dedicated +**Pull Request review requested** email when that recipient has **Settings → +Notifications → Discussion activity → Email** enabled. The email names the +contributor, PR number, and repository, and its **Review Pull Request** action +opens the same browser review. The person opening the PR is not sent a +self-notification. Email delivery is asynchronous; the Inbox and PR remain the +authoritative review surfaces. + +Reviewers should confirm: + +- the score belongs to the exact model revision under review; +- dataset revision, task, split, prompting, tools, and preprocessing are clear; +- the numeric value uses the benchmark's published metric definition; +- source links are accessible and do not expose credentials or private traces; +- the result does not duplicate an unchanged YAML file already on `main`. + +## Submit through the API + +The model-page contribution endpoint accepts the same values as the form and +requires an authenticated account with `community:write`: + +```http +POST /api/repos/{owner}/{name}/model-evaluation-submissions +Content-Type: application/json + +{ + "dataset_id": "cais/hle", + "task_id": "text-generation", + "value": 56, + "dataset_revision": "main", + "date": "2026-08-03", + "source_url": "https://example.com/evals/alice-qwen-demo-hle", + "source_name": "Release evaluation report", + "source_user": "alice", + "notes": "Revision v1.0, no tools" +} +``` + +The response contains the Pull Request, result-file path, contribution branch, +and commit revision. The service deliberately controls the branch and path; it +cannot be used as a general repository-write endpoint. + +Repository writers can still manage legacy database-backed records directly: | Operation | Route | | --- | --- | -| Read model links and evaluations | `GET /api/repos/{owner}/{name}/model-associations` | -| Add an evaluation | `POST /api/repos/{owner}/{name}/model-evaluations` | -| Update an evaluation | `PATCH /api/repos/{owner}/{name}/model-evaluations/{evaluationId}` | -| Delete an evaluation | `DELETE /api/repos/{owner}/{name}/model-evaluations/{evaluationId}` | +| Read model links and all evaluations | `GET /api/repos/{owner}/{name}/model-associations` | +| Create a legacy record | `POST /api/repos/{owner}/{name}/model-evaluations` | +| Update a legacy record | `PATCH /api/repos/{owner}/{name}/model-evaluations/{evaluationId}` | +| Delete a legacy record | `DELETE /api/repos/{owner}/{name}/model-evaluations/{evaluationId}` | -An evaluation request supplies `suite`, `metric`, and `score`; it may also -include `task`, `unit`, `source_url`, and `details`. Repository write permission -is required for changes. Use the live [OpenAPI Explorer](/spaces/mega/openapi) -for the complete schema and response contract. +Those management routes require repository write permission. New community +contributions should use `.eval_results` Pull Requests so the score, review, +and merge history stay together. ## Release checklist -- Evaluate the exact revision you publish, not an untracked local checkout. -- Name the metric and unit unambiguously; a raw score alone is rarely useful. -- Link to enough method detail for a reader to understand the result. -- Keep evaluation claims consistent with the repository card and cited paper. +- Evaluate a pinned model revision, not an untracked local checkout. +- Record the exact benchmark dataset and task identities. +- Include enough protocol detail for a reviewer to interpret the value. +- Keep claims consistent with the model card and cited source. +- Merge only after reviewing the generated YAML diff. - Update or remove stale results when a release changes behavior. diff --git a/hub/model-widgets.md b/hub/model-widgets.md index 95ce3da..61d9936 100644 --- a/hub/model-widgets.md +++ b/hub/model-widgets.md @@ -1,9 +1,47 @@ # Model Widgets -MEGA does not automatically create an interactive widget from model-card -metadata. To publish an interactive demo, create a [Space](/docs/hub/spaces) -that pins the model repository revision and explains any input or usage limits. +A model page shows an inline chat widget when the live Inference Provider +catalog contains a healthy `chat-completions` route for the same `owner/model` +ID. Model-card metadata alone does not make a widget available. -Keep a model card focused on the artifact and evaluation evidence. Keep demo -code, browser behavior, and interactive secrets in the Space workflow rather -than assuming a repository card executes code. +## Chat on the model page + +Sign in, choose **Auto** or a specific live Provider, enter a message, and select +**Send**. Auto uses MEGA's managed route selection. **View code snippets** opens +the token-based API examples; **Compare providers** opens the live catalog. + +The browser sends the signed-in session to the Hub. The Hub performs inference +server-side through the normal routed-inference control plane, so Provider +credentials are never returned to the page. Widget requests use the signed-in +account's MEGA Inference balance and can return `402` when its credit or spending +limit cannot cover the reservation. Review +[Pricing and Billing](/docs/inference-providers/pricing-and-billing) before +sustained use. + +Anonymous model chat is disabled. A model with only Responses or Embeddings +routes shows its available tasks but does not present a fake chat composer. + +## Conversations on this device + +The model widget and Docs Assistant use the same reusable conversation runtime: + +- multiple named conversations; +- new, select, delete, and clear-history actions; +- retry and in-flight cancellation behavior; +- account-scoped browser storage; +- a bounded recent-message history sent with the next request. + +Transcripts stay in local browser storage on the current device. They are not +synced to the repository, the model publisher, another device, or MEGA's server +conversation history. Signing into a different account uses a different local +scope. Clear the widget history to remove saved transcripts from that browser. + +Do not submit secrets, private datasets, or credentials in a prompt. Local +history is a convenience boundary, not a secret vault. + +## Publish a richer demo + +The inline widget intentionally covers a simple managed chat task. For custom +controls, multimodal inputs, generated artifacts, or an application-specific +workflow, create a [Space](/docs/hub/spaces) that pins the model revision and +documents its input, cost, and safety limits. diff --git a/hub/models.md b/hub/models.md index 2c75188..dc3d42a 100644 --- a/hub/models.md +++ b/hub/models.md @@ -41,6 +41,19 @@ The root `README.md` may declare Hugging Face YAML metadata. Card `description` Publish reproducible benchmark evidence with [Model Evaluations](/docs/hub/model-evaluations). Keep the score, metric, task, source, and release revision aligned with the model card. +On the model page, repository relationships are grouped as a model tree, Spaces +using the model, Collections including the model, and paper or article +references. The inference panel is separate: it reflects live model-to-Provider +routes rather than card tags. MEGA-native artifacts also receive a +[MegaTensors metadata summary](/docs/megatensors/package_reference/format#hub-repository-metadata-card) +from bounded inspection of the selected `.mega` file or `.mega.index.json`. + +When a healthy `chat-completions` route exists, the same panel includes a +signed-in [Model Widget](/docs/hub/model-widgets). It uses the account's MEGA +Inference balance, supports Provider selection, and keeps bounded multi-session +history in account-scoped local browser storage. Model publishers cannot enable +the widget by adding card markup; the live Provider mapping is authoritative. + Fallback metadata can be updated without rewriting the card: ```bash diff --git a/hub/notifications.md b/hub/notifications.md index 76d04fe..b1d6d1f 100644 --- a/hub/notifications.md +++ b/hub/notifications.md @@ -19,7 +19,13 @@ it. ## Choose activity preferences Open **Settings → Notifications** to control whether repository activity and -discussion activity appear in your inbox. Security and essential account +discussion activity appear in your inbox and whether each category can also be +delivered by email. Pull Request review requests belong to discussion activity. +Their dedicated email identifies the contributor, PR, and repository and links +directly to the browser review. +Email delivery is asynchronous and preference-controlled; the Inbox and the +underlying Pull Request remain authoritative if an email is delayed. Security +and essential account notices remain visible so that an account cannot accidentally hide information needed to protect access. From aaecb700c6b02e7862f7f39b375ee4c05d7948a0 Mon Sep 17 00:00:00 2001 From: bluemoon-o2 <2095774200@qq.com> Date: Thu, 6 Aug 2026 10:29:12 +0800 Subject: [PATCH 3/4] docs(api): remove public pricing endpoint --- hub/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/api.md b/hub/api.md index 16bb5ad..a6acb5a 100644 --- a/hub/api.md +++ b/hub/api.md @@ -117,7 +117,7 @@ OAuth, SCIM, Git LFS, and OpenAI-compatible inference follow their protocol-spec | Spaces runtime | `/api/spaces/*` | | Webhooks | `/api/me/webhooks/*` | | Papers | `/api/papers/*` | -| Pricing and billing | `/api/pricing`, `/api/billing/*` | +| Billing (authenticated) | `/api/billing/*` | ## Choose a client From 35edd31b0d305c74fafa97be610ef9ea6ef6dd42 Mon Sep 17 00:00:00 2001 From: bluemoon-o2 <2095774200@qq.com> Date: Mon, 10 Aug 2026 09:19:31 +0200 Subject: [PATCH 4/4] feat: publish MEGA documentation updates --- ai-native/_toctree.yml | 2 + ai-native/chat-plugins.md | 149 ++++++++++++++++++++++++++++++++++++++ ai-native/index.md | 4 +- hub/mcp.md | 7 +- 4 files changed, 160 insertions(+), 2 deletions(-) create mode 100644 ai-native/chat-plugins.md diff --git a/ai-native/_toctree.yml b/ai-native/_toctree.yml index 3e3595d..5ee12af 100644 --- a/ai-native/_toctree.yml +++ b/ai-native/_toctree.yml @@ -7,6 +7,8 @@ - title: Plugin and MCP sections: + - local: chat-plugins + title: Plugins in TensorPlayChat - local: using-the-plugin title: Use the MEGA Codex Plugin - local: mcp-workflows diff --git a/ai-native/chat-plugins.md b/ai-native/chat-plugins.md new file mode 100644 index 0000000..165d87f --- /dev/null +++ b/ai-native/chat-plugins.md @@ -0,0 +1,149 @@ +# Plugins in TensorPlayChat + +TensorPlayChat can install packages that follow the Codex plugin protocol. A +plugin is a package, not a product-specific integration: its manifest declares +the presentation metadata and points to Skills, MCP servers, Apps, hooks, and +assets included with the package. + +Cloudflare and GitHub are the first catalog entries. TensorPlayChat reads both +from the [official OpenAI plugin repository](https://github.com/openai/plugins) +and processes them through the same installer used for developer packages. +There is no Cloudflare- or GitHub-specific plugin schema. + +## Package layout + +The package root must contain `.codex-plugin/plugin.json`. Components use +paths relative to that root. + +```text +my-plugin/ +├── .codex-plugin/plugin.json +├── .mcp.json +├── .app.json +├── skills/ +│ └── inspect/SKILL.md +├── hooks/ +└── assets/ +``` + +The manifest must provide a kebab-case name, semantic version, description, +publisher, and interface metadata. Referenced component and asset paths must +stay inside the package. See the +[Codex plugin build guide](https://developers.openai.com/plugins/build/plugins) +for the upstream field contract. + +## Install from the catalog + +Open **Chat → Plugins**, choose a package, review its publisher, capabilities, +external service, and data-sharing notice, then select **Install**. Installation +does not silently authorize an external account. Configure each declared MCP +connection separately and keep **Allow actions without asking** off unless the +server and requested action set are trusted. + +The first catalog includes: + +- Cloudflare, from `openai/plugins/plugins/cloudflare`; +- GitHub, from `openai/plugins/plugins/github`. + +The package version, Skill instructions, connection endpoints, icons, and +other metadata come from the repository package rather than TensorPlayChat +source-code branches. + +## Create a Skill through Chat + +Open the **Skills** tab and select the **+** button. This starts the built-in +Skill Creator mode in the current conversation. Creation is deliberately +conversational rather than a one-shot form: + +1. The Agent asks for concrete examples, intended triggers, and boundaries. +2. It proposes a concise Skill name, trigger description, workflow, and any + genuinely reusable scripts, references, or assets. +3. It shows the final draft and asks you to reply **Approve and install** or + **批准并安装** in a later message. +4. After approval, the account tool validates and installs the Skill. + +The installer follows the same conventions as the built-in Codex +`skill-creator` and `skill-installer` workflows. It generates only the required +frontmatter fields, adds `agents/openai.yaml` UI metadata, enforces kebab-case +names and package size/path limits, and wraps the result in a normal plugin +package. The resulting source is marked **Created in Chat** and appears in the +same Skills list as Skills installed from catalog, repository, or ZIP packages. + +Enabled Skill instructions are applied to Chat automatically; they do not +depend on the remote MCP toggle. Bundled references are loaded on demand when +an enabled Skill requests them and **Plugins** mode is on. +Generated scripts are stored as package resources but are not executed during +creation or by the browser runtime. + +## Developer mode + +Enable **Developer mode** at the bottom of the Plugins view to reveal +**New plugin**. Developer mode provides three inputs: + +- **Repository** resolves a public HTTPS GitHub URL, optional ref, and optional + plugin subdirectory. The installer pins the ref to a commit before reading + package files. +- **Upload ZIP** accepts an archive containing one plugin root. The compressed + limit is 8 MiB, the expanded limit is 24 MiB, and a package may contain at + most 512 files. +- **Server URL** creates a protocol-compatible package around one remote HTTPS + MCP server. Use this for a custom MCP server that does not ship a complete + package yet. + +Developer packages are not reviewed. The installer rejects ambiguous roots, +path traversal, private or local server addresses, invalid manifests, missing +referenced assets, oversized component files, and unsupported repository URL +forms. A successful validation does not establish that the package or server +is trustworthy. + +## OAuth discovery and registration + +For an OAuth-protected remote MCP server, TensorPlayChat performs the standard +MCP authorization sequence: + +1. Call the MCP endpoint and read the `resource_metadata` URI from its + `401 Unauthorized` challenge. +2. Fetch OAuth Protected Resource Metadata and pin the advertised resource to + the configured MCP endpoint. +3. Discover OAuth Authorization Server Metadata and validate the issuer and + endpoints. +4. Use a Client ID Metadata Document (CIMD) when the server advertises + `client_id_metadata_document_supported`. +5. Otherwise, use Dynamic Client Registration (DCR) when a + `registration_endpoint` is advertised. +6. Complete Authorization Code with PKCE and an exact resource indicator. + +The discovery screen shows the authorization, token, registration, resource, +scope, and optional OpenID Connect metadata before authorization begins. CIMD +client metadata uses a public, opaque TensorPlayChat URL; it contains no +account identifier or credential. DCR client secrets, access tokens, refresh +tokens, and manually supplied bearer tokens are encrypted at rest and never +returned by the settings API. OAuth state is one-time and expires after ten +minutes. See the current +[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) +for the registration priority and protocol requirements. + +## Supported package surfaces + +| Surface | TensorPlayChat behavior | +| --- | --- | +| `.codex-plugin/plugin.json` | Validated and used for identity, discovery, consent, and presentation | +| `skills/*/SKILL.md` | Installed, individually switchable, visible with included files, and automatically supplied as bounded Chat guidance; text resources can be loaded on demand while Plugins mode is on | +| Remote HTTP MCP | Discovered and invoked through the bounded Chat tool loop | +| `.app.json` | Parsed and shown as package integration metadata; a connector ID is used only when the corresponding Chat connector is available | +| Hooks and other included files | Preserved and shown with the package; the Web runtime does not launch arbitrary local processes | +| Channels | Not supported | + +Local `stdio` MCP processes and arbitrary package executables cannot run in a +browser request. Publish a remote HTTPS MCP endpoint for Web Chat. This is a +runtime boundary, not a different plugin format: the package remains portable +to plugin hosts that provide those local capabilities. + +## Permissions and removal + +Each plugin and each Skill can be disabled without deleting the package. +Remote tools stay unavailable to the model while **Allow actions without +asking** is off. Disconnecting removes the stored connection credential; +removing the plugin deletes its account installation and OAuth state but does +not delete data at the external service. Revoke the external authorization at +that service as well when access should end completely. diff --git a/ai-native/index.md b/ai-native/index.md index 68bc2c5..6d9b8b6 100644 --- a/ai-native/index.md +++ b/ai-native/index.md @@ -9,6 +9,7 @@ other supported coding agents. | You want to… | Use… | | --- | --- | +| Add official or developer plugin packages to Web Chat | [Plugins in TensorPlayChat](/docs/ai-native/chat-plugins) | | Connect Codex to MEGA and install the bundled workflow guidance | The [MEGA Codex plugin](/docs/ai-native/install) | | Add only selected, portable MEGA workflow Skills | [MEGA Agent Skills](/docs/ai-native/skills) | @@ -29,6 +30,7 @@ You approve access through the normal MEGA authorization flow. Only grant the permissions needed for the task, and review the target before authorizing a write or deletion. -Start with [Install the MEGA Codex Plugin](/docs/ai-native/install), then see +For Web Chat, start with [Plugins in TensorPlayChat](/docs/ai-native/chat-plugins). +For Codex, start with [Install the MEGA Codex Plugin](/docs/ai-native/install), then see [MCP Workflows in Codex](/docs/ai-native/mcp-workflows) and the [MEGA Skills Catalog](/docs/ai-native/skills-catalog). diff --git a/hub/mcp.md b/hub/mcp.md index 40d2a77..677d34d 100644 --- a/hub/mcp.md +++ b/hub/mcp.md @@ -30,6 +30,7 @@ The hosted endpoint uses OAuth 2.1 with authorization-code PKCE and refresh toke | Community | `mega_collections`, `mega_content`, `repository_discussions` | Read and mutate collections, blog/community content, discussions, and pull requests. | | Guidance | `mega_doc_search`, `mega_doc_fetch` | Search ranked current documentation, then fetch the selected canonical Markdown page. | | MCP Marketplace | `mcp_market_search`, `mcp_market_details`, `mcp_market_call` | Search listings, inspect a publisher's current tool schemas, then invoke one paid tool through the Hub gateway. | +| Account memory | `memory_list`, `memory_search`, `memory_remember`, `memory_update`, `memory_forget`, `memory_set_enabled`, `memory_clear` | Inspect and explicitly manage durable account context with separate opt-in scopes. | Tool visibility is not authorization. OAuth scopes determine which actions can succeed, and the Hub rechecks ownership, organization policy, budgets, and billing on every call. Search responses include normalized canonical IDs, URLs, scores, match reasons, source, pagination state, and request diagnostics. Human-readable MCP content is only a concise summary; complete JSON appears once in `structuredContent`. @@ -51,7 +52,7 @@ authorization page use the same consent preference: - **Read** grants `repo:read`. - **Write** grants `repo:read`, `repo:write`, and `community:write`. -- **Full** grants all nine MEGA MCP access scopes. +- **Full** grants the nine standard MEGA MCP access scopes. Account Memory remains an explicit Custom choice. - **Custom** allows a dependency-safe selection. Available access scopes: @@ -66,6 +67,8 @@ inference:run mcp:use account:keys webhooks:manage +memory:read +memory:write ``` The default is Read. OAuth clients may additionally request `offline_access`; it allows refresh-token renewal and does not grant a MEGA data or action permission. @@ -83,6 +86,8 @@ Current focused-tool mapping: | `repo:delete` | Reserved for explicit repository deletion; no current focused MCP tool exposes it | | `account:keys` | CLI/account-settings key management; no MCP secret-bearing key tool | | `webhooks:manage` | CLI/API webhook management; no current focused MCP webhook tool | +| `memory:read` | List or search durable account context; Memory can be stale and never overrides the current request or system rules | +| `memory:write` | Remember, update, forget, enable, disable, or explicitly clear account memory | ## Connect ChatGPT Work