Data Mounts

PDAI-1 external volume layout and data_path() API

All bulk data lives on /Volumes/PDAI-1. Code in ~/ai-mac-studio/ never embeds hardcoded PDAI-1 paths — instead it uses platform_env.data_path("name").

Mount configuration

platform/config/data-mounts.yaml defines logical names:

mounts:
  pdai_collections:     /Volumes/PDAI-1/pdai-collections
  famulus_lake_catalog: /Volumes/PDAI-1/pdai-collections/_lake/famulus.ducklake
  famulus_lake_traces:  /Volumes/PDAI-1/pdai-collections/_lake/famulus_reference_traces.duckdb
  scholarly_data:       /Volumes/PDAI-1/2026projectdata/ai-scholarly
  agents_data:          /Volumes/PDAI-1/2026projectdata/ai-agents
  applevoicerecorder:   /Volumes/PDAI-1/2026projectdata/apps/ai-applevoicerecorder-data
  pdai_1_root:          /Volumes/PDAI-1
  project_data:         /Volumes/PDAI-1/2026projectdata
  ai_platform_data:     /Volumes/PDAI-1/2026projectdata/ai-platform
  ai_development_data:  /Volumes/PDAI-1/2026projectdata/ai-development
  ai_publication_data:  /Volumes/PDAI-1/2026projectdata/ai-publication
  ai_privat_data:       /Volumes/PDAI-1/2026projectdata/ai-privat

Key	Use
`famulus_lake_catalog`	DuckLake catalog of all famulus reference collections (DuckDB file; written only on mac-studio). Readers attach the read replica `famulus.read.ducklake` in the same folder. Only this key defines the production lake; env override `FAMULUS_LAKE_CATALOG` never does. See DuckLake
`famulus_lake_traces`	query-trace DB of the famulus-reference MCP server (`fr_run`, `fr_run_step`); written only by that server

On client machines code lives in ~/ai-openscience (Syncthing mirror of ~/ai-mac-studio) and /Volumes/PDAI-1 is mac-studio’s drive mounted via SMB.

Usage in code

from platform.shared.env import detect

env = detect()

# Get path to a named mount (raises if volume not mounted)
collections = env.data_path("pdai_collections")
# → Path("/Volumes/PDAI-1/pdai-collections")

# Get path or None if not present
data = env.data_path_if_present("applevoicerecorder")

Live health

Check current mount health in the admin UI: /admin/data-mounts or via the API: GET /api/data-mounts.

If /Volumes/PDAI-1 is not mounted, data_path() raises RuntimeError. Use data_path_if_present() to handle unmounted volumes gracefully.

apps/ai-applevoicerecorder data

The applevoicerecorder mount holds bulk media:

Subdirectory	Contents
`3d-reconstructions/`	Photogrammetry output meshes
`photos/`	Reference photos for 3D reconstruction
`videos/`	Source videos for video2mesh
`supplements/`	Supplementary materials
`calibration_labels/`	Camera calibration targets
Case PDFs	Scanned case documents