--- title: "Sharing a commons across projects" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Sharing a commons across projects} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set(eval = FALSE) ``` 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](../reference/commons.html) 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: ```{r calculation} #' 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: ```{r constructor} #' 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](https://r-pkgs.org/whole-game.html) walks through these steps if they're new to you. You can now build the commons and call the measure yourself: ```{r initialize} 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") ``` ```text 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: ````markdown --- title: "Survey counts" format: html --- ```{r`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()`: ```{r 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.