fn_registry/python/functions/infra/cache_to_file.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
cache_to_file	function	py	infra	1.0.0	impure	def cache_to_file(cache_dir: str, namespace: str = 'default') -> FileCache	Cache key-value donde cada entry es un archivo JSON en disco. Keys se hashean con SHA-256 para generar nombres de archivo seguros. Metadata (ttl, created_at, original_key) en sidecar .meta. Mejor que SQLite para valores grandes (PDFs procesados, embeddings).	cache file persistence ttl key-value sha256				false	error_go_core	os json hashlib time threading	name desc cache_dir directorio raiz donde se almacenan los archivos de cache name desc namespace namespace logico dentro de cache_dir para aislar diferentes cachés	instancia FileCache con metodos set, get, get_or_set, clear y stats	true	Set y get basico TTL expirado → None Archivo .meta con metadata correcta Clear elimina el directorio del namespace Key con caracteres especiales → hash seguro	python/functions/infra/cache_to_file_test.py	python/functions/infra/cache_to_file.py

Ejemplo

from infra.cache_to_file import cache_to_file

store = cache_to_file("/tmp/my_cache", namespace="embeddings")

# Almacenar un embedding grande
store.set("doc:123", embedding_vector, ttl=86400)

# Recuperar
vec = store.get("doc:123")

# Factory pattern
result = store.get_or_set(
    "pdf:page_42",
    factory=lambda: extract_pdf_text("doc.pdf", page=42),
    ttl=0,  # sin expiracion
)

Estructura en disco

cache_dir/
  namespace/
    {sha256_key}.json    # valor serializado como JSON
    {sha256_key}.meta    # {"created_at": ..., "expires_at": ..., "original_key": ...}

Notas

Cada entry genera exactamente dos archivos: .json para el valor y .meta para la metadata. La key original se guarda en .meta["original_key"] para facilitar debugging. Thread-safe mediante threading.Lock. La eviction es lazy: se verifica expires_at al hacer get.