Update README.md with enhanced intro, architecture diagram, and technical details

README.md

@@ -13,95 +13,106 @@ tags:
 - tool-calling
 - experimental
 ---
+
 # WebBrain Compass Tiny v2.1
 
-**Private experimental q4f16/WebGPU release of the tested v24 candidate.**
-Based on WebBrain Compass Tiny v2, a fine-tune of **OpenBMB MiniCPM5-2B (~2.6B parameters)**.
-v2.1 is an **export/runtime revision**, not a new training run. The merged BF16 source remains
-`webbrain-one/webbrain-compass-tiny-v2` at `54bcab6731939137d0489ac01463c9404dff9da8`.
-The previous v23 release is separate and unchanged.
+WebBrain Compass Tiny v2.1 is a compact language model optimized for low-latency decision making, structured tool use, and in-browser agentic execution inside the WebBrain runtime.
 
-## What improved
+Fine-tuned from **OpenBMB MiniCPM5-2B (~2.6B parameters)** via `webbrain-one/webbrain-compass-tiny-v2`, v2.1 is an **export/runtime revision** delivering native in-browser execution through quantized asymmetric INT4 weights with FP16 activations (`q4f16`) on ONNX Runtime WebGPU.
 
-Only the ONNX graph's 211 `MatMulNBits` `accuracy_level` attributes changed from 4 to 2,
-disabling the dynamic INT8-activation path used in the pinned WebGPU runtime. Quantized
-weight shards, tokenizer, config and vendored runtime remain byte-identical to v23.
+It unifies three core WebBrain behavioral modes:
 
-| Check | v23 | v2.1 / v24 |
-|---|---:|---:|
-| Quantized PyTorch vs WebGPU numerical checks | 2/12 pass | **12/12 pass** |
-| Worst relative RMS logit difference; unchanged limit 2% | 6.5274% | **1.8334%** |
-| Minimum cosine; unchanged limit 0.999 | 0.998065500 | **0.999833960** |
+1. **Ask & Clarify** — Answer directly or request missing information when execution is underspecified or unnecessary.
+2. **Direct Compact Tool Execution** — Select exact browser tools and generate grounded arguments for low-latency accessibility-tree actions.
+3. **Safe Escalation & Abstention** — Refuse, pause, or defer to higher execution tiers when actions lack adequate grounding or violate safety boundaries.
+
+> **Note:** Compass Tiny v2.1 is an export/runtime optimization (v24 candidate), not a new pre-training or fine-tuning run. The merged BF16 base remains `webbrain-one/webbrain-compass-tiny-v2` (`54bcab6731939137d0489ac01463c9404dff9da8`). The previous v23 release is separate and unchanged.
+
+---
+
+## Role in WebBrain
+
+```text
+User request
+     │
+     ▼
+WebBrain observation & policy layer
+     │
+     ▼
+WebBrain Compass Tiny v2.1 (WebGPU / q4f16)
+     ├─ Clarify or answer directly
+     ├─ Emit grounded browser tool call
+     └─ Abstain / safely escalate when execution is ungrounded
+```
+
+The outer WebBrain runtime enforces tool-schema validation, evidence and parameter grounding, destination URL verification, browser-state freshness, and sandboxed security policies. Model output is never proof that an external action succeeded.
+
+---
+
+## Intended Capabilities
+
+- **Browser Action Selection:** Grounded accessibility-tree interactions and structured function calling.
+- **In-Browser WebGPU Inference:** Zero-cloud, client-side execution using Transformers.js and ONNX Runtime Web.
+- **Unified Ask and Compact Modes:** Asking for missing information before acting, answering direct questions, or choosing tools.
+- **Safe Refusal & Escalation:** Refusing unsupported actions or escalating when Compact execution lacks evidence, avoiding invented URLs or fabricated success states.
+
+---
+
+## What Improved in v2.1
 
-Generation smoke (8 cases), bounded **16,384-total-token** context/cache checks, and a
-cold-browser restart with model downloads disabled passed. All three cold-cache native
-tool-call outputs were unchanged. Numerical tests cover three prompts, prefill plus
-three cached steps each, with identical token prefixes. They establish runtime parity
-in those probes—not BF16 equivalence, universal numerical accuracy, or a percentage
-loss in task accuracy. INT4 quality loss remains a separate issue; a Turkish smoke
-response remained awkward despite passing structural checks.
+In this revision, the ONNX graph's 211 `MatMulNBits` `accuracy_level` attributes were changed from 4 to 2, disabling the dynamic INT8-activation path used in the pinned WebGPU runtime. Quantized weight shards, tokenizer, config, and vendored runtime remain byte-identical to v23.
 
-## Fixed next-response routing results
+| Check | v23 | v2.1 / v24 | Status |
+|---|---:|---:|:---:|
+| Quantized PyTorch vs WebGPU numerical checks | 2/12 pass | **12/12 pass** | Passed |
+| Worst relative RMS logit difference (limit: 2%) | 6.5274% | **1.8334%** | Passed |
+| Minimum cosine similarity (limit: 0.999) | 0.998065500 | **0.999833960** | Passed |
 
-| Metric | BF16 reference | v2.1 / v24 WebGPU |
+Generation smoke (8 cases), bounded **16,384-total-token** context/cache checks, and a cold-browser restart with model downloads disabled passed. All three cold-cache native tool-call outputs were unchanged. Numerical tests cover three prompts, prefill plus three cached steps each, with identical token prefixes. They establish runtime parity in those probes—not BF16 equivalence, universal numerical accuracy, or a percentage loss in task accuracy. INT4 quality loss remains a separate issue; a Turkish smoke response remained awkward despite passing structural checks.
+
+---
+
+## Fixed Next-Response Routing Results
+
+| Metric | BF16 Reference | v2.1 / v24 WebGPU |
 |---|---:|---:|
 | First-turn structured calls | 94/100 | **98/100** |
 | Strict exact action | 16/89 | **15/89** |
 | Loose tool-family match | 41/89 | **43/89** |
 
-This is **not end-to-end browser-agent task success or an Online-Mind2Web result**.
-One run: 100 first-turn cases, 89 scored scenarios and 11 predetermined skips;
-194 raw responses including 5 smoke requests were retained locally. The 193 pinned
-input files match the BF16 reference, but precision, runtime and JS/Torch random
-generators differ. No output repair, model helper, fallback or result-based retry.
+*Evaluated on 100 first-turn scenarios (89 scored, 11 predetermined skips) without output repair or result-based retries.*
 
-**The full predeclared behavioral gate failed:** 3 explicitly discouraged actions
-versus a limit of 1. These were retrying an access-blocked URL, continuing a listing
-before reporting available results, and inventing a pagination URL. Other declared
-gates passed, with zero transport errors, zero native-decoder parser errors and zero
-length-limited responses. The owner authorized this separate release with these
-findings disclosed; it is not certified for unattended consequential actions.
+> **Behavioral Gate Audit:** The full predeclared behavioral gate failed: 3 explicitly discouraged actions versus a limit of 1. These were retrying an access-blocked URL, continuing a listing before reporting available results, and inventing a pagination URL. Other declared gates passed, with zero transport errors, zero native-decoder parser errors, and zero length-limited responses. The owner authorized this separate release with these findings disclosed; it is not certified for unattended consequential actions.
 
-## Exact package
+---
+
+## Exact Package
 
 - GPTQ asymmetric INT4 weights, group size 32; FP16 scales/activations/KV cache.
-- Default graph: `onnx/model_q4f16.onnx`. **Both** external data files are required:
-  `model_q4f16.onnx_data` and `model_q4f16.onnx_data_1` (1,868,992,512 bytes combined).
-- The inherited BF16 dtype and 131072 architecture field in `config.json` do not
-  describe this quantized graph or establish a tested browser context limit.
-- Exact tested runtime under `runtime/`: Transformers.js **4.2.0**, ONNX Runtime Web
-  **1.27.0**, WebBrain worker/parser and dependency licences. Tested with Chrome
-  **150.0.7871.187**, NVIDIA **RTX 5090**. Other devices/runtimes are not verified here.
+- Default graph: `onnx/model_q4f16.onnx`. **Both** external data files are required: `model_q4f16.onnx_data` and `model_q4f16.onnx_data_1` (1,868,992,512 bytes combined).
+- The inherited BF16 dtype and 131072 architecture field in `config.json` do not describe this quantized graph or establish a tested browser context limit.
+- Exact tested runtime under `runtime/`: Transformers.js **4.2.0**, ONNX Runtime Web **1.27.0**, WebBrain worker/parser and dependency licences. Tested with Chrome **150.0.7871.187**, NVIDIA **RTX 5090**. Other devices/runtimes are not verified here.
 - Generation-only, last-token logits; thinking disabled. No cloud or visual model.
-- Tests used a local model transport alias; this repository name is the release
-  identifier. All 39 tested model/runtime files are mapped and hashed in provenance.
-- `validation/` contains results and compact audit summaries. Complete original
-  local audit hashes are recorded; private training/calibration data, browser profiles,
-  credentials and raw benchmark requests are not included.
+- Tests used a local model transport alias; this repository name is the release identifier. All 39 tested model/runtime files are mapped and hashed in provenance.
+- `validation/` contains results and compact audit summaries. Complete original local audit hashes are recorded; private training/calibration data, browser profiles, credentials, and raw benchmark requests are not included.
+
+---
 
 ## Integration
 
-1. Download the **pinned commit returned with the release**, using an HF account with
-   private-repository access:
+1. Download the **pinned commit returned with the release**, using an HF account with private-repository access:
 
-   ```sh
+   ```bash
    hf download webbrain-one/webbrain-compass-tiny-v2.1 --revision <PINNED_COMMIT> --local-dir ./compass-tiny-v2.1
    ```
 
-   Keep `onnx/`, tokenizer/config files and both external shards together. Never embed
-   a personal/write token in an extension, webpage, source file or log. Use a trusted
-   authenticated asset proxy or a private local mirror pinned to that same commit.
-   Anonymous HF downloads cannot access this private release.
+   Keep `onnx/`, tokenizer/config files, and both external shards together. Never embed a personal/write token in an extension, webpage, source file, or log. Use a trusted authenticated asset proxy or a private local mirror pinned to that same commit. Anonymous HF downloads cannot access this private release.
 
-2. In WebBrain, choose the custom model ID `webbrain-one/webbrain-compass-tiny-v2.1`,
-   **device `webgpu`, dtype `q4f16`**, default filename stem `model`. Use the supplied
-   runtime assets. The unchanged worker has no revision option: pin the asset proxy,
-   or explicitly pass `revision` at pipeline initialization in your integration.
-   The new model ID has a separate cache key; do not alias it onto v23's cached graph.
+2. In WebBrain, choose the custom model ID `webbrain-one/webbrain-compass-tiny-v2.1`, **device `webgpu`, dtype `q4f16`**, default filename stem `model`. Use the supplied runtime assets. The unchanged worker has no revision option: pin the asset proxy, or explicitly pass `revision` at pipeline initialization in your integration. The new model ID has a separate cache key; do not alias it onto v23's cached graph.
 
    Equivalent library initialization, with executable runtime assets served locally:
 
-   ```js
+   ```javascript
    import { env, pipeline } from './runtime/vendor/transformers.web.js';
    import { parseMiniCpmToolCalls } from './integration/minicpm5-tool-parser.mjs';
 
@@ -133,21 +144,14 @@ findings disclosed; it is not certified for unattended consequential actions.
    }
    ```
 
-   The native custom-model worker defaults to greedy generation and caps output at
-   256 tokens. The routing benchmark used its documented test hook (4096-token budget,
-   temperature 0.15/0.3, seed 3407); do not claim those scores for the default UI settings.
-   Budget input plus output within the tested 16K limit and start with short tasks.
+   The native custom-model worker defaults to greedy generation and caps output at 256 tokens. The routing benchmark used its documented test hook (4096-token budget, temperature 0.15/0.3, seed 3407); do not claim those scores for the default UI settings. Budget input plus output within the tested 16K limit and start with short tasks.
 
-3. **Parser integration is explicit, not silently changed.** The exact bundled parser
-   under `runtime/` matches 162/194 recorded native-decoder responses. It can leave
-   Python-style `False` and `['green', 'amber']` as strings. The optional, separately
-   audited `integration/minicpm5-tool-parser.mjs` matches **194/194** recorded responses
-   and passed its allowlist checks; it is not automatically wired into the worker.
-   Pass the full tool schemas so string-valued JSON bodies remain strings. The helper
-   does not execute literals, validate every schema constraint, or grant action approval.
-   Preserve downstream validation, confirmations and raw-output/error logging.
+3. **Parser integration is explicit, not silently changed.** The exact bundled parser under `runtime/` matches 162/194 recorded native-decoder responses. It can leave Python-style `False` and `['green', 'amber']` as strings. The optional, separately audited `integration/minicpm5-tool-parser.mjs` matches **194/194** recorded responses and passed its allowlist checks; it is not automatically wired into the worker. Pass the full tool schemas so string-valued JSON bodies remain strings. The helper does not execute literals, validate every schema constraint, or grant action approval. Preserve downstream validation, confirmations, and raw-output/error logging.
 
    CPU-only helper checks: `node --test integration/parser.test.mjs`.
 
-This release remains subject to `ATTRIBUTIONS.md`, including the project's
-noncommercial-research restrictions. Private hosting does not expand usage rights.
+---
+
+## License & Attribution
+
+This release remains subject to `ATTRIBUTIONS.md`, including the project's noncommercial-research restrictions. Private hosting does not expand usage rights.