social-data-attribution-w2/docs/HCAI_LAB_NAMING_CONVENTION.md

HCAI-Lab HuggingFace Naming Convention

Last updated: 2026-05-24.

This document defines the naming convention for HuggingFace repositories (buckets, datasets, models, spaces) under the HCAI-Lab organization. Apply to every new repo. Existing repos were migrated to this convention in PR 3 (2026-05-24).

The rule

Lowercase letters, digits, and hyphens only. No underscores. No uppercase.

✅ HCAI-Lab/dolma3-6t-sample-500-docs
✅ HCAI-Lab/trackstar-scores-base-olmes-4bench
✅ HCAI-Lab/olmes-eval-olmo3-7b-base
✅ HCAI-Lab/archive-dolma3-pool-150b

❌ HCAI-Lab/dolma3_6T_sample_500_docs       (underscores + uppercase)
❌ HCAI-Lab/Trackstar-Scores                 (uppercase)
❌ HCAI-Lab/dolma3_6t_doc_ids                (underscores)

Reasons:

• Already used by all buckets and most newer datasets — smaller migration than the alternative
• URL-friendly: no escaping needed in shell, browser, or markdown
• Case-insensitive friendly: works on macOS / Windows / case-insensitive filesystems
• Matches the de facto HF Hub / GitHub convention

Repo-name structure

HCAI-Lab/<prefix>-<purpose-tokens>[-<axis-tokens>]

Where:

• <prefix> is one of:

  • dolma3- — Dolma 3 corpus, samples, manifests, sidecars, dedup state
  • trackstar- — TrackStar / Bergson attribution artifacts (gradient indices, query gradients, scores, preconditioners, top-K results, analysis)
  • olmes-eval- — OLMES evaluation result datasets
  • archive- — pre-6T-era datasets and other legacy work kept for reproducibility
  • (project-specific, e.g. tombench-) — other research projects under HCAI-Lab

• <purpose-tokens> describes what the repo holds. Examples: gradient-index, query-gradients, scores, corpus-manifest, bloom-index, bin-characterization.

• <axis-tokens> optional disambiguator for variants. Order: artifact-type → model → benchmark. Examples: base-olmes-4bench, instruct-cot-noprecond-mmlu-ss, olmo3-7b-base, gsm8k-arc, bbh.

Anti-patterns

• Do not embed SOC ticket numbers in repo names. Tickets are transient; the repo outlives them. Record SOC lineage in the repo README's "Provenance" section instead. (We dropped SOC# from 20 repos in PR 2 / PR 3 for this reason.)
• Do not use camelCase or PascalCase. Always lowercase.
• Do not use underscores. Always hyphens.
• Do not put project name as prefix when the org name already covers it. HCAI-Lab/data-attribution-olmes-... is redundant; we're already in the data-attribution org.
• Do not version numbers via -v2 etc. for incremental updates. Use the same name and let HF Hub track history. If a true breaking change is needed, prefix with archive- on the old version.

Dataset + bucket pairs

Some artifacts have both a Dataset surface (for dataset viewer + snapshot_download access) and a Bucket surface (for hf buckets sync / S3-style access). When both exist for the same data:

• Use the same canonical name across both surfaces.
• Both repos share the URL handle HCAI-Lab/<name>. HF treats datasets and buckets as separate repo types in the same namespace; they coexist without collision.
• Document the dual surface in the repo README so consumers know they can pick either path.

Example: the 500-docs sample is accessible as both:

• Dataset: https://huggingface.co/datasets/HCAI-Lab/dolma3-6t-sample-500-docs
• Bucket: hf://buckets/HCAI-Lab/dolma3-6t-sample-500-docs

Era markers

• Current: no prefix marker. Active work uses purpose-themed names without era hint.
• Archive: prefix archive-. Used for pre-6T-era datasets, deprecated query versions, and other legacy. Sorts visually below current work in alphabetical listings.

Provenance for renames

Every time a repo is renamed:

1. Add a ## Provenance section to its README listing old name, SOC lineage (if any), and rename date.
2. Add an old_names field to its entry in docs/data_home/inventory.json with the previous name(s).

This lets future readers trace any historical reference back to the current repo.

Open mappings (R2 ↔ HF)

The R2 bucket soc127-dedup still uses SOC-numbered prefixes (e.g., soc91-labels/, soc91-stats/, soc139-quality-sidecars/). Three HF datasets mirror these R2 prefixes and were intentionally left at their R2-matching names to preserve HF↔R2 parity:

• HCAI-Lab/soc91-labels ↔ R2 soc91-labels/
• HCAI-Lab/soc91-stats ↔ R2 soc91-stats/
• HCAI-Lab/soc139-quality-sidecars ↔ R2 soc139-quality-sidecars/

When R2 reorganization is undertaken (see docs/R2_FUTURE_REORG.md), these will be brought into the dashes-lowercase convention together with the R2 source. Until then, they are an intentional exception.

Enforcement

• New repo creation: follow this convention. If a name doesn't fit, propose the new pattern in a doc PR first.
• Renames are infrequent and require a Provenance README update + inventory.json update.
• The docs/data_home/inventory.json file is the canonical source of truth for what exists and what it's called.

Future home

The user has flagged a possible separate hcai-lab-org GitHub repository for org-level documentation in the future. When that exists, this naming-convention doc should move there so it applies across all HCAI-Lab projects, not just data-attribution.