Commons

Commons(
    client,
    data_sources,
    semantic_layer=None,
    context_layer=None,
    *,
    instructions=None,
)

A trustworthy agent that answers questions about its data.

Given a chatlas.Chat for the provider and model, the data sources it can query, and optionally a semantic layer of trusted calculations and a context layer of prose, a Commons agent will allow for agent interactions with answers classified by how they were produced.

A Commons agent inherits directly from chatlas.Chat and relies on the chatlas infrastructure to set up the LLM provider and model. Commons initializes its own chat state and system prompt to ensure provenance and citation tracking. Passing a custom system prompt in the Commons constructor is ignored with a warning; use instructions to add to commons’ prompt instead. For best results, enable thinking where the provider and model support it.

chat() and stream_async() are the currently supported ways to interact with a Commons agent. The other entry points chatlas offers (chat_async(), stream(), chat_structured(), etc.) are disabled and raise NotImplementedErrors because they are not (yet) tied in to the commons framework. The rest of chatlas’s surface works as it does on any chat.

data_sources is a DataSource, or a mapping of name to DataSource; a measure can take a named source’s connection as an argument named after it. instructions is extra text placed under an ## Additional instructions heading at the end of commons’ built-in system prompt, as a string or the path to a text or Markdown file.

Construction raises a TypeError if client is not a chatlas.Chat, if an entry of data_sources is not a DataSource, or if a layer is not the layer its argument claims; a ValueError if data_sources names no source or a measure asks for an injection no named source can fill; and a FileNotFoundError if instructions names a file that does not exist.

Methods

Name	Description
add_turn	Add a turn, restarting the citation request if a person spoke.
chat	Ask a question and wait for the whole answer.
citation_corpus	The trusted text this agent’s citations are verified against.
prewarm	Build the caches the first question would otherwise pay for.
queue_restore_reminder	Tell the next turn that the session behind its history is gone.
set_turns	Replace the conversation, dropping any reminder queued for it.
stream_async	Ask a question and stream the answer as it arrives.

add_turn

Commons.add_turn(turn)

Add a turn, restarting the citation request if a person spoke.

A user turn of nothing but tool results is the same question still running, and an assistant turn is nobody asking anything.

chat

Commons.chat(*args, echo='output', stream=True, kwargs=None)

Ask a question and wait for the whole answer.

A reminder queued with queue_restore_reminder() rides this turn, and a turn that fails leaves it queued for the next one.

citation_corpus

Commons.citation_corpus()

The trusted text this agent’s citations are verified against.

prewarm

Commons.prewarm()

Build the caches the first question would otherwise pay for.

Failures propagate: a direct call is typically warming caches ahead of a deployment, so a cold cache should fail the deploy.

queue_restore_reminder

Commons.queue_restore_reminder()

Tell the next turn that the session behind its history is gone.

set_turns

Commons.set_turns(turns)

Replace the conversation, dropping any reminder queued for it.

stream_async

Commons.stream_async(
    *args,
    content='text',
    echo='none',
    data_model=None,
    kwargs=None,
    controller=None,
)

Ask a question and stream the answer as it arrives.

The signature is identical to chatlas’s, so a chat UI can drive this agent directly and needs the attachment content, the mode, and the controller its stop button cancels through.

The Commons agent does not accept data_model. If you pass it, this method raises NotImplementedError. In chatlas, using data_model means the chunks are JSON that the caller parses as one document. Commons adds provenance markers and citations to the stream that are not compatible with data_model, so it is explicitly forbidden.