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.