sdk-python: decide the validation-error contract (own type vs pydantic.ValidationError)

[peteski22]

Context

The Python SDK's Pydantic models validate on construction and raise pydantic.ValidationError for every failure — id/superseded_by format, extensions keys, duplicate_of, confidence bounds, and (as of #510) the free-text length and array-cardinality ceilings.
That type is not re-exported from cq or listed in __all__, so a consumer must import pydantic and catch pydantic.ValidationError — an undocumented, third-party contract.

By contrast the SDK's operational failures have cq-owned types: RemoteError, FallbackError, DuplicateUnitError, DiscoveryError, TTLError. Validation is the odd one out.

#510 documented the current behavior (models module docstring + a Raises: on create_knowledge_unit) as an interim step. This issue tracks the actual decision.

Options

• A (done in feat(sdk-python): enforce free-text ceilings from the schema package #510): document that construction raises pydantic.ValidationError.
• B: re-export ValidationError (Pydantic's) in cq.__all__ so consumers get a cq-namespaced handle (from cq import ValidationError). Cheap, but it is Pydantic's type — no real decoupling.
• C: define a cq-owned exception (for example InvalidUnitError, possibly a small hierarchy) and wrap pydantic.ValidationError at the construction boundaries. True decoupling, but a real change: direct Insight(...)/KnowledgeUnit(...) construction raises Pydantic's type unless the base model is overridden, which fights Pydantic and discards its structured .errors() detail.

Scope

SDK-wide — affects every model validator, not just the length ceilings. Any decision should also consider whether the Go SDK wants a parallel contract.

Refs #510, #504.