docs/hf_auth_integration_notes.md

HuggingFace Authentication Integration Notes

Purpose

Allow users to save their Big RPG Scale entity databases to their own HuggingFace datasets (avoiding data collection concerns).

Requirements

• Space-level OAuth configuration
• User authentication via gr.LoginButton()
• Save/load to user's own HF datasets

README.md Changes Required

---
title: GameConfigIdeaEditBrainstorm
hf_oauth: true
hf_oauth_scopes:
  - read-repos
  - write-repos
---

Gradio OAuth Integration

Login Button

import gradio as gr

with gr.Blocks() as demo:
    gr.LoginButton(variant="huggingface", size="sm")

Access User Profile

def my_function(profile: gr.OAuthProfile | None):
    if profile:
        username = profile.username
        # Can now save to user's repos
    else:
        return "Please log in first"

Access User Token

def save_to_user_dataset(
    profile: gr.OAuthProfile | None,
    token: gr.OAuthToken | None,
    data: str
):
    if not profile or not token:
        return "Login required"

    # Use token.token for API calls

Implementation Functions

Save Database

from huggingface_hub import HfApi, create_repo

def save_database_to_hf(
    db: EntityDatabase,
    profile: gr.OAuthProfile,
    token: gr.OAuthToken,
    dataset_name: str = "rpg-entity-database"
) -> str:
    username = profile.username
    repo_id = f"{username}/{dataset_name}"

    api = HfApi(token=token.token)

    # Create repo if needed
    create_repo(repo_id, repo_type="dataset", exist_ok=True, private=True)

    # Export and upload
    db_json = db.to_json()
    api.upload_file(
        path_or_fileobj=db_json.encode('utf-8'),
        path_in_repo="entity_database.json",
        repo_id=repo_id,
        repo_type="dataset"
    )

    return f"Saved to: https://huggingface.co/datasets/{repo_id}"

Load Database

from huggingface_hub import hf_hub_download

def load_database_from_hf(
    db: EntityDatabase,
    profile: gr.OAuthProfile,
    token: gr.OAuthToken,
    dataset_name: str = "rpg-entity-database"
) -> str:
    username = profile.username
    repo_id = f"{username}/{dataset_name}"

    file_path = hf_hub_download(
        repo_id=repo_id,
        filename="entity_database.json",
        repo_type="dataset",
        token=token.token
    )

    with open(file_path, 'r') as f:
        json_str = f.read()

    success, message = db.from_json(json_str)
    return message

UI Integration

Entity Database Tab Addition

with gr.Row():
    login_btn = gr.LoginButton(variant="huggingface", size="sm")
    login_status = gr.Markdown("*Not logged in*")

with gr.Accordion("Cloud Save/Load (HuggingFace)", open=False):
    gr.Markdown("Save your entity database to your HuggingFace account.")

    hf_dataset_name = gr.Textbox(
        label="Dataset Name",
        value="rpg-entity-database"
    )

    with gr.Row():
        save_to_hf_btn = gr.Button("Save to HuggingFace", variant="primary")
        load_from_hf_btn = gr.Button("Load from HuggingFace")

    hf_status = gr.Markdown("")

Graceful Degradation

• All local features work without login
• Show gr.Info("Please log in...") when save/load attempted without auth
• Display current login status prominently

Alternative: CommitScheduler (Auto-Save)

For session logging (like D&D GM event logs):

from huggingface_hub import CommitScheduler

scheduler = CommitScheduler(
    folder_path="./user_data",
    repo_id=f"{username}/game-sessions",
    token=token.token,
    private=True
)

• Runs background thread, pushes every ~1 minute
• Good for append-only data (logs, feedback)
• Not ideal for frequently-updated files

Resources

• Gradio OAuth Docs
• Gradio OAuth Example Space
• HuggingFace Hub Upload Guide
• Spaces Persistent Storage

TODO

• Test OAuth flow locally with huggingface-cli login
• Decide on dataset structure (single JSON vs multiple files)
• Consider versioning/backup strategy
• Investigate Space-level persistent storage options