Commons

A trustworthy agent that answers questions about its data.

Usage

Source

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

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.