The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Sharing a commons across projects

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.

Put it in a package

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().

Use the commons across projects

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.