dgk-lab-runtime 0.1.0

Digital Gardening Kit — Lab notebook runtime utilities for Marimo notebooks in Obsidian vaults

dgk-lab-runtime

Lab notebook runtime utilities from the Digital Gardening Kit.

Designed for Marimo notebooks that live alongside an Obsidian vault — handles the runtime boundary between local ETL (filesystem, secrets, network) and the published HTML/WASM notebook. Works with any vault layout; the defaults follow the vault-seed conventions (lab/ as the notebooks path, public/lab/ as the dataset directory) which you can override via environment variables or function arguments.

Install

pip install dgk-lab-runtime
# with scraping support (Playwright)
pip install "dgk-lab-runtime[scraping]"
# with OCR support (Tesseract)
pip install "dgk-lab-runtime[ocr]"

Usage

from dgk_lab_runtime import (
    lab_runtime_context,
    read_lab_json,
    load_lab_manifest,
    read_lab_dataset,
    write_local_json_snapshot,
    fetch_local_feed,
    fingerprint_data,
    with_data_provenance,
)

ctx = lab_runtime_context()
# {"runtime": "local", "isPackaged": False, "capabilities": {...}, ...}

# Read a dataset from the Lab manifest (local or Pyodide/WASM)
data = read_lab_dataset("my-dataset")

# Write a versioned JSON snapshot to the vault
write_local_json_snapshot("40 - Recursos/data/snapshot.json", data)

Configuration

Environment variable	Default	Description
VAULT_NOTEBOOKS_PATH	lab	URL segment where notebooks are published

Runtime boundary

Every function that writes files, reads secrets, or makes outbound requests calls require_local_runtime() and raises RuntimeError when running inside a packaged HTML/WASM notebook. This boundary is intentional: ETL logic runs locally before export; the published notebook only reads pre-generated snapshots.

Vault-seed compatibility

If you use vault-seed, the _lab_notebook_runtime.py shim in 99 - Meta e Anexos/Notebooks/ imports this package transparently when installed, so existing notebooks work unchanged. Without installation the shim uses an inline fallback — same API, no external dependency.

License

GPL-3.0-only — see LICENSE.md in the repository root.