From 016a701ee871303d6bfe8d1e7c9de0b17f5089af Mon Sep 17 00:00:00 2001 From: Luke Scott Date: Thu, 17 Sep 2026 16:48:10 +1000 Subject: [PATCH] docs(registry): group each role's model and effort anchors in variables examples --- docs/targets/factory.md | 55 +++++++++++-------- .../valid/shared/variables-anchor-bucket.yaml | 52 ++++++++++-------- tests/test_registry.py | 12 ++-- 3 files changed, 66 insertions(+), 53 deletions(-) diff --git a/docs/targets/factory.md b/docs/targets/factory.md index ea02e62..cacc002 100644 --- a/docs/targets/factory.md +++ b/docs/targets/factory.md @@ -26,33 +26,38 @@ clientConfig: `simple`, and `validator`. Session and mission model fields may use portable references or Factory-native IDs. -## Sharing model references +## Sharing role models and efforts The optional root `variables` bucket holds YAML anchors that any client -configuration reuses through aliases, so each role model is written once: +configuration reuses through aliases, so each role's model and reasoning +effort are written once: ```yaml variables: - worker: &worker_model - provider: openrouter - model: gpt-5-mini - worker_effort: &worker_effort max - thinker: &thinker_model - provider: openrouter - model: gpt-5 - thinker_effort: &thinker_effort max - orchestrator: &orchestrator_model - provider: openrouter - model: gpt-5 - orchestrator_effort: &orchestrator_effort max - simple: &simple_model - provider: openrouter - model: gpt-5-mini - simple_effort: &simple_effort max - validator: &validator_model - provider: openrouter - model: gpt-5 - validator_effort: &validator_effort max + worker: + model: &worker_model + provider: openrouter + model: gpt-5-mini + effort: &worker_effort max + thinker: + model: &thinker_model + provider: openrouter + model: gpt-5 + effort: &thinker_effort max + orchestrator: + model: &orchestrator_model + provider: openrouter + model: gpt-5 + effort: &orchestrator_effort max + simple: + model: &simple_model + provider: openrouter + model: gpt-5-mini + validator: + model: &validator_model + provider: openrouter + model: gpt-5 + effort: &validator_effort max clientConfig: factory: @@ -80,8 +85,10 @@ clientConfig: `variables` is an anchor bucket only: ModFig requires it to be a mapping and never interprets its content, because the YAML loader expands the aliases before the parser sees the values. Anchors must be defined before the first -alias that uses them. `simple_effort` has no Factory effort slot today -(subagent fields are model-only). +alias that uses them. Because nothing reads the bucket, its grouping is +free-form; nesting `model` and `effort` under each role keeps one role's +settings together. `simple` has no effort anchor because Factory stores no +effort for `subagent` fields, which are model-only. ## Factory TUI session default diff --git a/spec/fixtures/valid/shared/variables-anchor-bucket.yaml b/spec/fixtures/valid/shared/variables-anchor-bucket.yaml index d90ae47..c041b90 100644 --- a/spec/fixtures/valid/shared/variables-anchor-bucket.yaml +++ b/spec/fixtures/valid/shared/variables-anchor-bucket.yaml @@ -1,30 +1,34 @@ -# AC-13.1: the optional root `variables` bucket carries one YAML anchor per -# Factory default role plus one reasoning-effort anchor per role; client -# configuration reuses them through aliases. The YAML loader resolves the +# AC-13.1: the optional root `variables` bucket carries one YAML anchor pair per +# Factory default role, grouping the role's model and reasoning-effort anchors. +# Client configuration reuses them through aliases. The YAML loader resolves the # aliases before the reference parser sees the values. -# simple_effort is currently unused: subagent fields are model-only. +# `simple` has no effort anchor: Factory stores no effort for subagent fields. specVersion: "0.1" variables: - worker: &worker_model - provider: router - model: primary - worker_effort: &worker_effort high - thinker: &thinker_model - provider: router - model: primary - thinker_effort: &thinker_effort max - orchestrator: &orchestrator_model - provider: router - model: primary - orchestrator_effort: &orchestrator_effort max - simple: &simple_model - provider: router - model: primary - simple_effort: &simple_effort high - validator: &validator_model - provider: router - model: primary - validator_effort: &validator_effort max + worker: + model: &worker_model + provider: router + model: primary + effort: &worker_effort high + thinker: + model: &thinker_model + provider: router + model: primary + effort: &thinker_effort max + orchestrator: + model: &orchestrator_model + provider: router + model: primary + effort: &orchestrator_effort max + simple: + model: &simple_model + provider: router + model: primary + validator: + model: &validator_model + provider: router + model: primary + effort: &validator_effort max providers: router: name: Router diff --git a/tests/test_registry.py b/tests/test_registry.py index 74c667b..5762ea6 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -1128,15 +1128,17 @@ def test_registry_rejects_invalid_or_unsafe_base_urls(base_url: str) -> None: def test_top_level_variables_anchor_bucket_with_aliases() -> None: - # ponytail: one anchor definition reused across factory core via aliases. + # ponytail: one grouped anchor pair per role reused across factory core + # via aliases. content = textwrap.dedent( """\ specVersion: "0.1" variables: - worker: &worker_model - provider: router - model: primary - worker_effort: &worker_effort high + worker: + model: &worker_model + provider: router + model: primary + effort: &worker_effort high providers: router: name: Router