richfrem/project_sanctuary/hf-upload

HuggingFace Upload Primitives

Status: Active Author: Richard Fremmerlid Domain: HuggingFace Integration Depends on: hf-init (credentials must be configured first)

Purpose

Provides consolidated upload operations for all HF-consuming plugins (Primary Agent, Orchestrator, etc.). All uploads include exponential backoff for rate-limit handling.

Available Operations

Usage

From Python (as a library)

from hf_upload import upload_file, upload_soul_snapshot, append_to_jsonl
# Upload a single file
result = await upload_file(Path("my_file.md"), "lineage/my_file.md")
# Upload a sealed learning snapshot
result = await upload_soul_snapshot(Path("snapshot.md"), valence=-0.5)
# Append records to soul_traces.jsonl
result = await append_to_jsonl([{"type": "learning", "content": "..."}])

Prerequisites

1. Run hf-init first to validate credentials and dataset structure
2. Requires huggingface_hub installed (pip install huggingface_hub)
3. Environment variables: HUGGING_FACE_USERNAME, HUGGING_FACE_TOKEN

Error Handling

All operations return HFUploadResult with:

• success: bool — whether the upload succeeded
• repo_url: str — HuggingFace dataset URL
• remote_path: str — path within the dataset
• error: str — error message if failed

Rate-limited requests retry with exponential backoff (up to 5 attempts).