External integrations

zot has three boundaries beyond ordinary in-memory planning: the local Zotero SQLite database, the optional semantic sidecar, and Zotero file storage. Their dependencies and effects are intentionally different.

library(data.table)
#> 
#> Attaching package: 'data.table'
#> The following object is masked from 'package:base':
#> 
#>     %notin%
library(zot)

Boundary	Reads or effects	Operational note
Local SQLite	Read-only local query	May lag synchronized API state
Semantic sidecar	Read-only Chroma query through Python	Depends on an existing index
File attachment	Creates an item and may upload bytes	Has immediate API and storage effects

Query SQLite read-only

zotLocalQuery() opens the supplied database with SQLite’s read-only flag and closes the connection when the query returns. This small fixture demonstrates the boundary without depending on an installed Zotero client.

Path <- tempfile(fileext = ".sqlite")
Connection <- DBI::dbConnect(RSQLite::SQLite(), Path)
DBI::dbWriteTable(
  Connection,
  "items",
  data.frame(key = c("A", "B"), title = c("One", "Two"))
)
DBI::dbDisconnect(Connection)

zotLocalQuery(
  "SELECT key, title FROM items WHERE key = ?",
  params = list("B"),
  path = Path
)
#>       key  title
#>    <char> <char>
#> 1:      B    Two
unlink(Path)

zotLocalItems() knows Zotero’s client schema and returns non-trashed regular items with library and date fields:

Items <- zotLocalItems(library = "user")
Items[, .(key, itemType, title, dateModified)]

The desktop client may be in WAL mode or awaiting synchronization. These rows are useful for a scan, not for proving a remote write succeeded.

Query the optional semantic sidecar

ztSemantic() launches the Python interpreter installed with zotero-mcp-server and queries its zotero_library Chroma collection. The defaults target one common Unix uv installation; other layouts must provide pythonPath and dbPath explicitly.

Results <- ztSemantic(
  "conditional mean spectrum ground motion selection",
  limit = 5L
)
Results[, .(itemKey, title, distance)]

The function does not install Python, create the Chroma database, or run zotero-mcp update-db. Refreshing the index is a separate operation, and its results can lag current API data. The current query has no library selector: limit applies across all indexed personal and group records, and groupID is returned so callers can inspect their origin.

Exercise the attachment protocol offline

ztAttach() creates an attachment item, requests storage authorization, uploads bytes when needed, registers the upload, and verifies the server-side MD5. The example supplies a fake API performer and a transport that reports an identical file already present, so no bytes leave the process.

File <- tempfile(fileext = ".pdf")
writeBin(as.raw(1:8), File)

Performer <- function(config, method, path, query, body, version) {
  list(
    status = 200L,
    headers = list(),
    body = list(successful = list(`0` = list(key = "ATT1")))
  )
}

Config <- zotConfig(
  userID = "42",
  key = "example-key",
  performer = Performer
)

Transport <- list(
  authorize = function(...) list(exists = 1L),
  upload = function(...) stop("upload should not run"),
  register = function(...) stop("registration should not run")
)

ztAttach(
  Config,
  parentKey = NA_character_,
  filePath = File,
  fileTransport = Transport
)
#> $status
#> [1] "exists"
#> 
#> $key
#> [1] "ATT1"
unlink(File)

With the default transport, this call has immediate external effects and may consume Zotero storage quota. A file-bearing record is refused by the block-move planner because that planner does not transfer attachment bytes.

Keep evidence in the correct plane

A curation workflow may discover candidates through SQLite or semantic search, establish current versions through the API, and upload an attachment. The same functions can be invoked interactively, from scripts, or by agent applications. API reads are required to observe remote outcomes; local data sources can lag the synchronized library.