# Freedom Intelligence — open-weight inventory entry schema
# Each collected (or tracked) model revision is one YAML file under catalog/
# Filename suggestion: {org}__{name}__{short_revision}.yaml
#
# Schema version documents field meaning for humans and future validators.
schema_version: "0.1.0"

# ---------------------------------------------------------------------------
# Example entry (illustrative only — not a real collection claim)
# ---------------------------------------------------------------------------
# id: meta-llama__Llama-3.2-3B-Instruct__abc1234
# status: candidate | approved | collecting | collected | verified | superseded | evicted | rejected
# name: Llama-3.2-3B-Instruct
# org: meta-llama
# source:
#   kind: huggingface  # huggingface | github_release | direct_url | other
#   url: https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct
#   revision: abc1234def...   # commit sha, tag, or release id
#   model_card_url: https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct
# license:
#   spdx: llama3.2          # or MIT, Apache-2.0, etc.; use "custom" + notes if needed
#   url: https://...
#   allows_offline_retention: true
#   allows_local_ops: true
#   allows_fine_tune: true
#   notes: ""
# artifacts:
#   - path: blobs/model.safetensors
#     sha256: "..."
#     bytes: 0
# size:
#   total_bytes: 0
#   total_human: "0 B"
# hardware_class:
#   # Rough lab guidance — not a guarantee
#   min_vram_gb_q4: 4
#   min_vram_gb_fp16: 8
#   notes: "fits consumer 8GB at Q4"
# axes:                    # why this matters to the lab
#   - B
#   - C
# priority: medium         # low | medium | high
# collection:
#   approved_by: ""
#   approved_at: null      # ISO-8601 date
#   downloaded_at: null
#   downloaded_by: ""
#   storage_path: ""       # absolute or facility-relative path on backup storage
#   brief_refs:            # briefs that nominated this candidate
#     - briefs/2026/07/2026-07-23.md
# reason: "Strong small instruct base; clear license; homelab-fit."
# tags:
#   - instruct
#   - text
# companions: []           # optional related catalog ids (adapters, tokenizers)
# notes: ""
# history:
#   - at: "2026-07-23"
#     event: nominated
#     by: operator
#     detail: "From daily brief collection candidates."

# ---------------------------------------------------------------------------
# Required fields by status (normative for humans; tooling may enforce later)
# ---------------------------------------------------------------------------
# candidate:  id, status, name, org, source.url, source.revision, license, reason, priority
# approved:   + collection.approved_by, collection.approved_at
# collected:  + collection.downloaded_at, collection.storage_path, size, artifacts[].sha256
# verified:   + checksums re-read OK (notes or history event)
# rejected:   + reason (why rejected)
# superseded / evicted: + history event; storage_path may be empty after eviction

field_reference:
  id:
    type: string
    description: Stable catalog id; prefer {org}__{name}__{short_revision}
  status:
    type: enum
    values: [candidate, approved, collecting, collected, verified, superseded, evicted, rejected]
  name:
    type: string
  org:
    type: string
  source:
    type: object
    fields: [kind, url, revision, model_card_url]
  license:
    type: object
    fields: [spdx, url, allows_offline_retention, allows_local_ops, allows_fine_tune, notes]
  artifacts:
    type: list
    item_fields: [path, sha256, bytes]
  size:
    type: object
    fields: [total_bytes, total_human]
  hardware_class:
    type: object
    fields: [min_vram_gb_q4, min_vram_gb_fp16, notes]
  axes:
    type: list
    values: [A, B, C, D]
  priority:
    type: enum
    values: [low, medium, high]
  collection:
    type: object
    fields: [approved_by, approved_at, downloaded_at, downloaded_by, storage_path, brief_refs]
  reason:
    type: string
  tags:
    type: list
  companions:
    type: list
  notes:
    type: string
  history:
    type: list
    item_fields: [at, event, by, detail]