Layering & Precedence

Yosoi policy is layered. Each layer is a partial Policy. Only fields explicitly set by a layer participate in the merge.

CLI precedence

For CLI runs, the effective order is:

env < global policy files < project policy files < --policy sources < CLI flags

Higher layers win.

Python precedence

In Python, call Policy.cascade(...) yourself:

policy = ys.Policy.cascade(
    ys.Policy.from_env(),
    team_policy,
    project_policy,
    contract_policy,
    call_site_policy,
)

The last policy wins when layers set the same field.

Nested merge behavior

Nested policy objects field-merge. This means a project can set one output option while preserving another option from a lower layer.

# global
output:
  formats: [json]
  flat_files: true

# project
output:
  formats: [jsonl]

Effective result:

output:
  formats: [jsonl]
  flat_files: true

Model credential firewall

model has one important special rule. If a higher layer changes provider or model_name, it replaces the model identity so a lower layer’s credentials cannot accidentally travel to a different provider.

Safe pattern:

model:
  provider: groq
  model_name: llama-3.3-70b-versatile
  credential_ref:
    source: env
    name: GROQ_KEY

Effective policy

Use this before running a scrape when you are not sure which layer is winning:

uvx yosoi policy effective --format yaml

To test only explicit sources and skip discovery:

uvx yosoi policy effective --no-discover --policy .yosoi/policy/test.yaml --format yaml