[david-debest]

Fixes #75

What

The Knowledge Engine has no optional values in bindings. This adds two sentinels that serialize to <http://www.knowledge-engine.eu/mapper/undefined>:

Sentinel	Type	Use for
UNDEFINED	URIRef	Uri fields
UNDEFINED_LITERAL	single member of enum UndefinedLiteral	Literal[T], Datatype-annotated and RdfLiteral fields

• Incoming bindings with the URI deserialize to the sentinel that matches the field type (check with is), never to None.
• Using the wrong sentinel for a field type raises a ValidationError, and pyright flags it too.
• None is not converted automatically; dump_result_binding() still rejects it.
• In dump_partial_binding() and matches_with, the sentinels are concrete values, not wildcards.

Why an enum for literals

Pyright accepts an enum member in literal fields and narrows it away. For a Literal[int] field, x is not None and x is not UNDEFINED_LITERAL narrows to int. A URIRef sentinel can't be narrowed like that.

Typing change: literal field hints are now T | UndefinedLiteral | None. Pyright will flag code that only checks for None before using a literal value.

The enum branch is Strict(), so a bare URI string (no <>) is not turned into the sentinel.

Docs

README (API section and examples table), examples/README.md, CONTEXT.md, and a new examples/13-undefined_values.py.

Testing

• uv run pytest: all tests pass, including new sentinel tests in tests/test_bindings.py.
• Typing checked with pyright 1.1.414 against the package; it isn't part of the project tooling.
• The example handler was called directly; it was not run against a live KE.

Related

• Fix BindingModel.matches_with for Literal and Datatype fields #76: matches_with fails for Literal and Datatype fields (existing bug)
• Pyright reports BindingModel fields as required despite None default #77: pyright reports BindingModel fields as required (existing bug)