Suppose you’ve collected your team’s trusted calculations in a commons. You want an agent to use them, but you also need those same calculations in Quarto reports, Shiny apps, or scheduled workflows. When you change a calculation, you don’t want to update a copy in every project.
You can put the code that builds the commons in an R package, then call it from each project.
Let’s call the package surveys. In
inst/measures/biodiversity.R, define a measure that totals
survey counts by site:
#' Individuals observed by site
#'
#' Counts recorded during surveys, not a complete population census.
#' @measure
individuals_by_site <- function(survey_db) {
DBI::dbGetQuery(
survey_db,
"SELECT site, SUM(count) AS individuals FROM observations GROUP BY site ORDER BY site"
)
}The @measure annotation marks the function as a trusted
calculation. Keeping the file under inst/ lets commons read
its source and annotations after installation. (If you prefer to define
the function in R/, use measure() instead of
the roxygen2-style annotation.)
In R/biodiversity_commons.R, export a function that
builds the commons:
#' Create the survey commons
#' @param observations A data frame with site and count columns.
#' @return A commons object.
#' @export
biodiversity_commons <- function(observations) {
commons::commons(
data_sources = list(
survey_db = commons::data_source(observations = observations)
),
semantic_layer = commons::semantic_layer(
system.file("measures", package = "surveys", mustWork = TRUE)
)
)
}Add commons and DBI to Imports in
DESCRIPTION, then run devtools::document() and
install the package. R
Packages walks through these steps if they’re new to you.
You can now build the commons and call the measure yourself:
observations <- data.frame(
site = c("Oak Bluff", "Oak Bluff", "Pine Ridge"),
count = c(12, 8, 5)
)
biodiversity <- surveys::biodiversity_commons(observations)
biodiversity$measure("individuals_by_site") site individuals
1 Oak Bluff 20
2 Pine Ridge 5
This returns a data frame without calling a model. You can also call
metrics (from data-dict.yaml definitions) with
$metrics() and exact trusted queries (if you use
Snowflake/Databricks) with $calculation().
A Quarto report can now read survey data and call the trusted calculation directly:
---
title: "Survey counts"
format: html
---
```{r}
observations <- read.csv("observations.csv")
biodiversity <- surveys::biodiversity_commons(observations)
biodiversity$measure("individuals_by_site")
```To build an agent, pass the commons to agent():
biodiversity <- surveys::biodiversity_commons(observations)
agent <- commons::agent(
client = ellmer::chat("anthropic/claude-sonnet-5"),
commons = biodiversity
)When the same commons is used across projects, those various projects will use whatever trusted code is contained in the commons. So, after updating the package in a consuming project, the next report render or app restart uses the revised code.