Python semantic layer: Injected marker and the @measure decorator

[jat255]

First of four stacked PRs building the Python semantic layer (M3). This one adds the measure record and the rule that tells the two kinds of measure argument apart.

These are implemented in pkg-py/src/commons/_measures.py and corresponding tests.

Two types of measures:

• The model supplies parameters annotated as Annotated[T, Field(description=...)]
• commons supplies parameters annotated Injected[T] and they never reach the model.

A parameter that is neither raises TypeError at decoration time. This came from decision D9, and it is stricter than the R package, where a forgotten @param silently hides an argument from the model.

Some API notes

@measure returns the function unchanged and attaches the record as an attribute, so measures and the helpers they call stay ordinary callables.

The schema is not built through chatlas, because Tool.from_func() rejects any model whose fields do not cover every function parameter, which won't work on injected parameters. Measures are never registered with the provider in any case, since the provider sees only call_measure.

Argument validation uses pydantic's model_validate on an extra="forbid" model. That covers unknown arguments, required arguments, enum vocabularies, and coercion in one call, so there is no need for a hand-written validator. Its error text differs from the R package's, which is accepted because the text goes back to the model as a tool error rather than to a user.

One caveat worth noting: An Annotated Field carrying default= or default_factory= is a decoration error, and the default belongs in the signature instead.

For example, the following will not work:

@measure
def discount_rate(
    order_id: Annotated[str, Field(description="The order to price.")],
    rate: Annotated[float, Field(description="Discount fraction.", default=0.1)],
) -> float:
    ...

validate_args omits unset arguments so that Python applies the default at call time. Accepting a Field default would make the schema optional while the signature still required the argument, and the call would then fail mid-conversation.

Not in this PR: semantic_layer(), injection resolution, and the public exports. Those are the PRs above it in the stack.

for my own future reference, the thumbs up below is an indication that I've approved this PR for myself, while the remaining PRs in the stack are awaiting my manual reivew

Four signature mistakes are rejected at decoration rather than left to fail later, because each one produces a measure that can never run. A parameter that is neither described nor injected, a positional-only parameter (the caller passes arguments by keyword), an async def or async generator (it would hand a coroutine to the model), and a parameter marked both described and injected, which would otherwise vanish from the schema in silence.

One error deserves its own mention. Annotating Injected[Engine] and importing Engine under if TYPE_CHECKING: is the way this feature is meant to be used, and get_type_hints() would fail it with a bare NameError: name 'Engine' is not defined under a stack of typing internals. It now raises naming the measure, the unresolved name, and the two ways out.