Commons

A trustworthy agent that answers questions about its data.

Usage

Source

Commons(
    client,
    data_sources,
    semantic_layer=None,
    context_layer=None,
    *,
    instructions=None,
    network="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.

The agent can run Python code that its model writes. The code runs in a separate, sandboxed Python process, which starts the first time the model runs code. network sets whether that process can reach the network: "none" (the default) or "full". The sandbox works on Linux and macOS. For local development on another system, set the COMMONS_ALLOW_UNSAFE_FALLBACK environment variable to run the code with limited checks instead. Warning! These checks are not intended to be a security boundary.

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, a measure asks for an injection no named source can fill, or network is neither "none" nor "full"; a FileNotFoundError if instructions names a file that does not exist; and a RuntimeError if this host cannot sandbox the session and the opt-in is not set.