AGENT SKILL

mctx

Use Mctx for JAX-native Monte Carlo tree search, MuZero/Gumbel MuZero policies, stochastic MuZero search, and search-tree inspection.

License 许可
Apache-2.0
最近更新
2026-09-03
Stars
★ 351
Forks
27

01 前言 Front Matter

name
mctx
license
Apache 2.0
metadata
{ "disco-role": "operating" }
description
Use Mctx for JAX-native Monte Carlo tree search, MuZero/Gumbel MuZero policies, stochastic MuZero search, and search-tree inspection.
disable-model-invocation
true

02 资源文件 7

03 SKILL.md 正文

Mctx

Mctx is a compact JAX library for batched Monte Carlo tree search. Use this skill when the task asks you to plan with a learned model, improve a policy with search, or inspect the resulting search tree.

Start here

  • Install the library with pip install mctx.
  • If you want a quick health check, run python scripts/check_install.py.
  • If you want a safe runnable example, run python scripts/policy_improvement_demo.py --num_runs=1.
  • Read references/api-reference.md when you need exact function signatures or tensor-shape contracts.
  • Read references/workflows.md when you need an end-to-end recipe.
  • Read references/troubleshooting.md when search output, shapes, or optional dependencies are failing.

What this skill covers

1. Batched search on a learned model

Use search(...) when you already have:

  • a batched root state,
  • a recurrent model for expansion,
  • a root action-selection function,
  • an interior action-selection function,
  • and a simulation budget.

This is the lowest-level entry point and is best when you need to customize the search loop.

2. Classic MuZero-style planning

Use muzero_policy(...) when you want the standard MuZero policy improvement loop with Dirichlet root noise, PUCT-style action selection, and visit-count based action weights.

3. Gumbel MuZero planning

Use gumbel_muzero_policy(...) when you want the Gumbel MuZero variant and its default Q-value completion strategy. This is the best default when the task mentions policy improvement by planning with Gumbel.

4. Stochastic MuZero planning

Use stochastic_muzero_policy(...) when the environment alternates between decision nodes and chance nodes. Provide separate decision and chance recurrent functions; the wrapper handles the internal state structure.

How to choose the right helper

  • Use qtransform_by_parent_and_siblings for the default MuZero-style value normalization.
  • Use qtransform_completed_by_mix_value for the default Gumbel MuZero path.
  • Use qtransform_by_min_max when you already know a bounded Q-value range.
  • Prefer the policy helper that matches the search style instead of reaching into _src internals.

Inspecting results

After search, prefer the public summary APIs over raw tree fields unless you are troubleshooting.

  • PolicyOutput.action is the chosen action.
  • PolicyOutput.action_weights are the training targets for the policy head.
  • PolicyOutput.search_tree holds the final Tree.
  • Tree.summary() exposes root visit counts, visit probabilities, value, and Q-values.
  • Tree.qvalues(node_index) is the best way to inspect a node.

Common input contract

  • Treat action masks as 1 = invalid, 0 = valid.
  • Keep root and recurrent outputs batched.
  • Make prior_logits and invalid_actions have the same trailing action dimension.
  • Keep recurrent_fn outputs aligned with the batch size of the root.
  • Use max_depth only when you intentionally want to cap traversal depth.

Bundled scripts

  • scripts/check_install.py verifies the installed package, imports the public API, and reports the active JAX backend.
  • scripts/policy_improvement_demo.py is a tiny bandit-style smoke demo that shows how planning can improve a policy.

Optional dependency note

This skill does not bundle tree visualization. If you need Graphviz-style tree rendering later, treat it as a separate dependency problem instead of assuming it is available in a minimal install.

When to read the deeper references

  • Read references/api-reference.md before wiring a custom model or action mask.
  • Read references/workflows.md before writing a new MuZero or Gumbel MuZero driver.
  • Read references/troubleshooting.md when output is flat, invalid-action handling looks wrong, or JAX is on the wrong backend.
  • Read references/repo-provenance.md when you need to check whether this skill is stale against the source checkout that produced it.

04 同仓库更多 Skills

VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-triton-opt

Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-solve

END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-skill

PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-pattern-fusion

Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-orchestrate

Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-feedback

Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).

★ 351