Skip to content

docs: callout that policy_guardrails now raises AdapterSchemaMismatchError instead of ValueError #1413

Closed

Description

@planetf1

Summary

PR #1357 (closes #1332) changed policy_guardrails's both/neither input validation from raising ValueError to raising AdapterSchemaMismatchError (extends Exception, not ValueError). This is intentional and correct — AdapterSchemaMismatchError has been the standard schema-mismatch exception since Phase 0 (#1134, PR #1158) and is already the exception mellea.intrinsic.parse_failures (see #1140) increments on — but it's a breaking change to a public function's exception contract that isn't documented anywhere a downstream caller would find it.

policy_guardrails's own docstring already has a Raises: entry for the new type (added in #1357), but nothing else references the change: no changelog entry (this repo's CHANGELOG.md is auto-generated from PR titles with no "Breaking Changes" section), and docs/AGENTS_TEMPLATE.md (the guide for code that imports Mellea) says nothing about it.

Scope

Add a short note to docs/AGENTS_TEMPLATE.md (or wherever downstream-facing behavior changes are tracked) flagging that any caller doing except ValueError around policy_guardrails needs to add except AdapterSchemaMismatchError as well, since it merged in v0.7.0 (2026-07-13) without a public callout.

Priority

Low — this is a documentation gap, not a code defect. No urgency, but worth tracking rather than letting it go unrecorded.

Epic: #929

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions