stringforge.vulcan.Vulcan

Contents

stringforge.vulcan.Vulcan#

class stringforge.vulcan.Vulcan(*, repo, staging_dir=None, run_id_template='{date}_{project}_h11-{h11?}_h12-{h12?}_ks-{ks_id?}_triang-{triang_id?}_seed-{seed?}', project='', token=None, budget=90, window_s=3600.0, extra_kwargs=None)#

Bases: object

Per-repo handle for the production vacuum-forging pipeline.

A Vulcan instance is bound to a single HuggingFace repo and a single local staging directory. Workers call write() to stage validated shards; a head node (cron job, daemon, or python -m stringforge.vulcan sync) calls sync() to push them to the Hub. Multiple Vulcan instances may co-exist in the same process to write to different repos – useful for cross-project workflows where different paper drafts target different production repos.

See stringforge.vacua_writer.VacuaWriter for the curated counterpart that targets the paper-aligned vacua_vault repo.

Parameters:

  • repo (str) – "user/repo" on HuggingFace. Required; no global default. Override per-call via sync() with repo=....

  • staging_dir (Union[str, Path, None]) – Local staging root. Resolution order is documented in resolve_staging_dir().

  • run_id_template (Union[str, Callable[..., str], None]) – Either a format string with {name} / {name?} placeholders, a callable returning the run_id, or None for the UUID fallback. See runid.

  • project (str) – Default {project} value for the run-id template.

  • token (Optional[str]) – HuggingFace write token. Falls back to STRINGFORGE_VULCAN_TOKEN then HF_TOKEN at sync time.

  • budget (int) – Commits-per-hour ceiling. Defaults to 90 (10-commit margin below HuggingFace’s 100/hour cap).

  • window_s (float) – Rolling-window length, in seconds, over which budget applies. Defaults to 3600 s.

  • extra_kwargs (Optional[Mapping[str, Any]]) – Default substitutions for the run-id template applied to every write() call. Per-call extra_kwargs= arguments take precedence.

Raises:

ValueError – When repo is empty.

See the module page for the curated public method index. The class page is kept as the canonical object target for cross-references and the general index.

Contents