commons (version 0.0.1)

data_source: Create a data source

Description

A data source combines a DBI connection with a table registry for a commons() agent. The agent queries the connection directly; no data is copied.

Usage

data_source(..., tables = NULL, dictionary = NULL)

Value

A commons_data_source object.

Arguments

...

A single DBI connection.

tables

Tables to describe in the agent's system prompt. Supply a character vector of table names, schema-qualified strings such as "schema.table", or DBI::Id objects. The registry does not restrict which tables the connection can query. The default is every table returned by DBI::dbListTables(). Strings containing dots are treated as schema-qualified names; use DBI::Id(table = "a.b") for a literal table name containing dots.

dictionary

An optional path to a data dictionary describing the source's tables and columns, in the data-dict.yaml format. See the Data dictionaries section.

Data dictionaries

A data dictionary records what each table's rows represent, what its columns mean, allowed values and units, table relationships, and domain terms. commons uses it in three places:

• The dataset-level description and details, along with the glossary, appear in the system prompt. Use these fields for rules that span tables and guidance about which tables answer a question.

• The first time a conversation touches a table---via the describe_table tool or a SQL query---the tool result includes that table's prose, documented columns, relationships, and relevant glossary definitions. describe_table merges documented columns with the live schema.

• The search_context tool searches the dictionary's prose, with one passage for each table and glossary term.

Trust

Before passing a query to the database, the run_sql tool checks its leading statement keyword against a denylist of common data- and schema-modifying operations. The check is a keyword filter; database permissions remain the access-control boundary. Open the connection in read-only mode where the backend supports it, and grant it access only to the tables the agent needs.

See Also

commons() to build an agent over one or more data sources.

Examples

if (requireNamespace("duckdb", quietly = TRUE)) {
  con <- DBI::dbConnect(duckdb::duckdb())
  DBI::dbWriteTable(
    con,
    "sales",
    data.frame(region = c("EMEA", "APAC"), revenue = c(100, 200))
  )

  src <- data_source(con)
  src$tables

  DBI::dbDisconnect(con, shutdown = TRUE)
}