feat(py): the Commons class, its assembly order, chat() and stream_async()

[jat255]

Summary

Assembles the pieces the rest of M5 landed into an agent that answers a question. Per D1 this composes chatlas.Chat as a private ._client rather than inheriting from it, so the public surface is a decision R never had to make.

Commons(client, data_sources, semantic_layer=None, context_layer=None, *, instructions=None). The constructor validates, then assembles in R's order. data_sources takes one DataSource or a mapping of them.

Implementation

Construction. A bare source is filed under an internal key and offers nothing to inject, which matches R's have_name() filter. Three arguments in the port plan's signature are absent: network only ever gates the execution tool, and run_python belongs to M6, while log and share_with are tracing arguments and _tracing.py does not exist. Each would be a parameter that does nothing until the milestone that gives it meaning adds it with its gate.

The client is not taken over. The agent builds its own chat from the client's provider, as pkg-r/R/commons.R does, so it never changes an object its caller still holds. A system prompt on the client is ignored with a warning, in R's wording. Both warnings about state the client carried fire before any other argument is checked, in R's order, so a bad later argument does not eat them. Model parameters carry over, read from the attribute behind set_model_params() because chatlas has no getter, and written back through the public setter; if that attribute is missing or is no longer a mapping, the agent warns and names the setter rather than dropping a temperature in silence. kwargs_chat is copied one level deep. The provider itself is shared, because it carries the model, which is also true of client$get_provider() in R.

stream_async() takes chatlas's signature without data_model, whose chunks are JSON to be parsed whole and would not survive an appended marker. It accepts extra positional content, a content= mode and a StreamController, which is the shape shinychat calls with, so the Shiny surface can drive an agent without an adapter that reimplements the scanner. Every str chunk goes through the citation scanner and only the projection is yielded, so reserved markup never reaches a browser. The provenance tag is derived after the stream from the collected tags and the scanner's verified flag, and the aside is yielded last. A consumer that walks away without cancelling still closes the provider's stream.

prewarm() covers the context store and each source with no try/except, so a cold cache fails a deploy rather than warning.

Divergence from R

R starts a new conversation and loses history on the handed-over client in silence. This warns and names agent.set_turns(). History is data the caller created, and now that the client is not mutated it is recoverable, since the caller still holds it. R has no such warning because R has never had a reason to look.

Deliberately absent

• No OpenTelemetry spans, including commons_agent_create, which w0t2 retrofits in one sweep.
• No conversation-id accessors, per D5.
• No semantic_models or calculations registry, since both read warehouse semantic objects and that stays deferred.
• Commons is not exported from __init__.py. The export and the README example are 5mys, which keeps the README from claiming an import that does not resolve.

Tests

tests/_provider.py implements chatlas's Provider as a scripted replay, so the real chatlas.Chat runs the real tool loop and only the network call is scripted. anthropic is not a dependency here, so ChatAnthropic cannot be constructed in this suite.

The turn rules are pinned through both entry points: chat() and stream_async() each carry the reminder, citation-request-reset, and restore-reminder-spend tests, set_turns() is checked to forward rather than drop, and each of these was verified by deleting the line it guards and watching the test fail.

No new shared fixture. Nine existing fixtures already pin everything the assembly order is observable through, and the order has no output of its own. The one unpinned cross-language claim is this stream's emission order, which needs a live streaming harness that R's own streaming tests skip without development ellmer. 5mys is asked to decide whether the end-to-end path earns a fixture, and it will have that harness.

Verified: ruff check, pyrefly check src tests, and pytest (1289 passing). No R files changed.