# 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.2.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...
#   model_card_url: https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct
#   project_url: https://www.llama.com/   # optional: org project / paper home
#   paper_url: https://arxiv.org/...     # optional
# license: { ... }
# profile:
#   summary: "One-line what this model is for."
#   original_source: "https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct"
#   use_cases:
#     - "Always-on local assistant on small VRAM"
#     - "Edge classification and simple tool routing"
#   sweet_spots:
#     - "Latency-sensitive chat under 3–8 GB VRAM"
#     - "Teaching / prototyping agent loops cheaply"
#   not_ideal_for:
#     - "Hard multi-file software engineering"
#     - "Long-horizon reasoning"
#   capability_notes: >
#     Compact instruct model; strong ecosystem tooling; limited depth vs mid-size.
# swot:
#   strengths:
#     - "Tiny footprint; huge Llama tooling ecosystem"
#   weaknesses:
#     - "Shallow reasoning and coding vs 8B–70B class"
#   opportunities:
#     - "Domain LoRA for NetKingdom micro-agents"
#   threats:
#     - "Superseded quickly by next small open release"
# size: { ... }
# hardware_class: { ... }
# axes: [B]
# priority: high
# collection: { ... }
# reason: "..."
# tags: [tier-r, instruct]
# companions: []
# notes: ""
# history: []

# ---------------------------------------------------------------------------
# Required fields by status
# ---------------------------------------------------------------------------
# candidate:  id, status, name, org, source.url, source.revision, license,
#             reason, priority, profile (summary + original_source + use_cases +
#             sweet_spots), swot (all four lists, compact)
# approved:   + collection.approved_by, collection.approved_at
# collected:  + collection.downloaded_at, collection.storage_path, size, artifacts
# verified:   + checksums re-read OK
# rejected:   + reason
# superseded / evicted: + history event

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, project_url, paper_url]
  license:
    type: object
    fields: [spdx, url, allows_offline_retention, allows_local_ops, allows_fine_tune, notes]
  profile:
    type: object
    description: Human-facing capability card for operators choosing models
    fields:
      summary: One-line positioning
      original_source: Canonical URL (usually HF model card or org release page)
      use_cases: List of typical lab / product uses
      sweet_spots: Where the model punches above weight or is the default pick
      not_ideal_for: Explicit anti-patterns
      capability_notes: Short free-text capability narrative
  swot:
    type: object
    description: Compact SWOT for reserve / ops decisions (2–4 bullets each)
    fields: [strengths, weaknesses, opportunities, threats]
  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]