feat(integrations): wire HuggingFace import (G06) — offline core tested, hub-fetch honestly gated (#55)

## What

Resolves **G06** — the HuggingFace dead-code / overclaim knot.
`src/integrations/huggingface.jl` was 825 lines that were:
- **not included** from `src/Axiom.jl` (unreachable),
- `using JSON3` — a dependency that had been **removed** from
`Project.toml` (so it would fail to load if revived), and
- headed by a `✓ Current Status (v0.2.0)` block claiming ✓ for features
that could not run.

Rather than delete cold code (estate doctrine #7), it's **wired** — and
the claims made honest.

## How

- **JSON3 → JSON** port (JSON is already a `[deps]`, so no new
dependency; removes the removed-dep landmine).
- **Wired** into `src/Axiom.jl`; fixed the two bugs wiring exposed:
- imported the Axiom internals it uses that aren't on the exported
surface (`Pipeline`, `AbstractLayer`, `parameters`);
- dropped `verify_model` from the export list — it was **exported but
never defined** (an undefined export Aqua flags).
- **Tested**: `test/integrations/huggingface_tests.jl` exercises the
network-free core — architecture detection, model building into an Axiom
`Pipeline` (BERT 18 layers / GPT-2 13 layers), SafeTensors dtype
mapping, and the pure verification report.
- **Honest header**: the `✓` block is replaced with capability tiers —
*wired+tested (offline)* / *present-but-needs-network* /
*not-implemented*. Notes that the `@prove` lines in
`verify_imported_model` are placeholder comments, not proofs.
- **Docs reconciled** (`docs/wiki/Ecosystem.md`): the contradictory "⚠
Beta" table row + "not a shipped API" prose now state the offline import
is shipped+tested and the hub-fetch path requires network.

## Verification (ground-truthed by running the tools)

- `Pkg.test()` → **732/732 green** with HF wired, **Aqua + JET
included** (undefined-export fix confirmed; no ambiguities; no JET
regressions).
- Offline smoke confirmed independently: `detect_architecture` → "bert",
`build_model_from_config` → 18-layer `Pipeline`,
`_safetensors_dtype("F32")` → `Float32` / `"BF16"` → `nothing`.

The network hub-fetch path
(`from_pretrained`/`get_model_info`/`download_file`) is present and
honestly documented as network-required (needs `AXIOM_HF_TOKEN` for
private models) — **not** exercised in CI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---
_Generated by [Claude
Code](https://claude.ai/code/session_01UPFC9YQ7g9gc3VnRox42Q1)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

docs/wiki/Ecosystem.md

@@ -253,8 +253,13 @@ model = from_pytorch("model.pytorch.json")
 
 ### HuggingFace
 
-HuggingFace direct import remains a roadmap item and is not a shipped API in
-the current baseline.
+HuggingFace support is wired into Axiom (`Axiom.HuggingFaceCompat`). The
+offline core — architecture detection, model building into an Axiom `Pipeline`
+(BERT/GPT-2/RoBERTa/ViT/ResNet/Llama/Whisper), and SafeTensors weight loading —
+is shipped and exercised by the test suite. The network hub-fetch path
+(`from_pretrained` downloading by model id) is present but requires network
+access (and `AXIOM_HF_TOKEN` for private models), so it is not exercised in CI.
+Tokenizers are not implemented (use Transformers.jl).
 
 Current recommended path:
 
@@ -491,7 +496,7 @@ upload_blob("models", "axiom/model.axiom", "model.axiom")
 | ONNX | ⚠ Beta | Export API shipped for Dense/Conv/Norm/Pool + activation Sequential/Pipeline subset |
 | PyTorch | ⚠ Beta | Import API shipped for canonical JSON descriptor + direct `.pt/.pth/.ckpt` bridge |
 | TensorFlow | ⚠ Beta | Via ONNX |
-| HuggingFace | ⚠ Beta | Selected models |
+| HuggingFace | ⚠ Beta | Offline import wired + tested (config→architecture→build + SafeTensors); hub-fetch present but requires network |
 | **Tracking** | | |
 | MLflow | ✓ Stable | Full support |
 | W&B | ✓ Stable | Full support |

src/Axiom.jl

@@ -132,6 +132,7 @@ include("serving/api.jl")
 
 # Integrations
 include("integrations/interop.jl")
+include("integrations/huggingface.jl")  # HuggingFace model import (G06: wired; hub-fetch needs network, offline import/build/verify is exercised)
 
 # Re-exports for user convenience
 export @axiom, @ensure, @prove, @no_grad

src/integrations/huggingface.jl

@@ -1,40 +1,54 @@
 # SPDX-License-Identifier: MPL-2.0
 # Axiom.jl HuggingFace Integration
 #
-# Import pretrained models from HuggingFace Hub with security verification.
+# Import pretrained models from HuggingFace into Axiom.
 #
-# Current Status (v0.2.0):
-# ✓ HuggingFace Hub API integration
-# ✓ Model metadata fetching
-# ✓ File downloading with caching
-# ✓ Architecture detection (BERT, RoBERTa, GPT-2, ViT, ResNet)
-# ✓ Security verification (@prove integration)
-# ✓ SHA256 checksum verification
-# ✓ Architecture conversion (BERT, RoBERTa, GPT-2, ViT, ResNet)
-# ✓ SafeTensors weight loading (pickle-free)
-# ⚠ PyTorch .bin weight loading (requires Python conversion to SafeTensors)
-# ✗ Tokenizer support (use Transformers.jl instead)
+# Status is stated honestly by capability, not as a flat "✓ done" list — the
+# offline core is wired into Axiom and exercised by the test suite
+# (test/integrations/huggingface_tests.jl); the hub-fetch layer requires the
+# network and is therefore NOT exercised in CI.
 #
-# Recommended Workflow:
-# 1. Export HF model to ONNX: model.save_pretrained("model", export=True)
-# 2. Import via Axiom: model = load_onnx("model/model.onnx")
-# 3. Verify: verify(model, properties=[FiniteOutput(), ValidProbabilities()])
+# WIRED + TESTED (offline, network-free):
+#   - Architecture detection from a config Dict (detect_architecture).
+#   - Model building into an Axiom Pipeline for BERT / GPT-2 / RoBERTa / ViT /
+#     ResNet / Llama / Whisper, plus a generic-transformer fallback
+#     (build_model_from_config and the build_* builders).
+#   - SafeTensors dtype mapping and header parsing (_safetensors_dtype,
+#     _load_safetensors!); pickle-free.
+#   - A structural verification report (verify_imported_model).
 #
-# Future Work:
-# - Full PyTorch .bin weight loading
-# - Complete architecture builders (GPT-2, ViT, ResNet)
-# - Integrated tokenizer support
-# - Quantization-aware conversion
-# - Model card parsing for metadata
+# PRESENT, requires network (NOT exercised in CI):
+#   - Hub metadata fetch (get_model_info) and file download (download_file),
+#     and the from_pretrained orchestrator that drives them. These need network
+#     access and, for private models, the AXIOM_HF_TOKEN environment variable.
+#   - SHA256 checksum verification of a downloaded file (verify_model_hash).
+#
+# NOT implemented (honest gaps, not silent failures):
+#   - Tokenizers — use Transformers.jl (load_tokenizer is a documented stub).
+#   - PyTorch .bin (Python pickle) weight loading — convert to SafeTensors first.
+#   - The `@prove` lines inside verify_imported_model are PLACEHOLDER comments,
+#     not active proofs; do not treat that report as formal verification.
+#
+# Roadmap: full .bin support, richer architecture builders, integrated
+# tokenizers, quantization-aware conversion, model-card metadata parsing.
 
 module HuggingFaceCompat
 
 using HTTP
-using JSON3
+using JSON
 using SHA
 using ..Axiom
-
-export from_pretrained, load_tokenizer, verify_model
+# Explicitly bring in the Axiom internals this module uses that are not part of
+# Axiom's exported surface (so `using ..Axiom` alone would not see them):
+#   Pipeline      — the layer-container type (`const Sequential = Pipeline`)
+#   AbstractLayer — element type of the layer vectors the builders assemble
+#   parameters    — per-layer parameter accessor used by the weight loaders
+using ..Axiom: Pipeline, AbstractLayer, parameters
+
+# Public surface. (`verify_model` was previously exported but never defined —
+# an undefined export; removed. Hash verification is `verify_model_hash`, kept
+# internal to the submodule.)
+export from_pretrained, load_tokenizer
 
 # HuggingFace Hub API endpoint
 const HF_HUB_URL = "https://huggingface.co"
@@ -110,7 +124,7 @@ function from_pretrained(
     end
 
     # Load configuration
-    config = JSON3.read(read(config_path, String))
+    config = JSON.parse(read(config_path, String))
 
     # Convert architecture
     architecture = detect_architecture(config)
@@ -175,14 +189,14 @@ function get_model_info(model_id::String, revision::String)
 
     try
         response = HTTP.get(url, headers=headers)
-        data = JSON3.read(String(response.body))
+        data = JSON.parse(String(response.body))
 
         ModelInfo(
             model_id,
             revision,
-            get(data, :architecture, "unknown"),
-            get(data, :num_parameters, 0),
-            get(data, :sha256, ""),
+            get(data, "architecture", "unknown"),
+            get(data, "num_parameters", 0),
+            get(data, "sha256", ""),
             ""
         )
     catch e
@@ -239,16 +253,16 @@ Detect model architecture from config.
 """
 function detect_architecture(config)
     # Check for architecture hints in config
-    if haskey(config, :model_type)
-        return String(config.model_type)
+    if haskey(config, "model_type")
+        return String(config["model_type"])
     end
 
-    if haskey(config, :architectures) && !isempty(config.architectures)
-        return String(config.architectures[1])
+    if haskey(config, "architectures") && !isempty(config["architectures"])
+        return String(config["architectures"][1])
     end
 
     # Heuristics based on config structure
-    if haskey(config, :num_hidden_layers) && haskey(config, :num_attention_heads)
+    if haskey(config, "num_hidden_layers") && haskey(config, "num_attention_heads")
         return "transformer"
     end
 
@@ -288,11 +302,11 @@ end
 Build BERT architecture.
 """
 function build_bert(config)
-    hidden_size = get(config, :hidden_size, 768)
-    num_layers = get(config, :num_hidden_layers, 12)
-    num_heads = get(config, :num_attention_heads, 12)
-    intermediate_size = get(config, :intermediate_size, 3072)
-    vocab_size = get(config, :vocab_size, 30522)
+    hidden_size = get(config, "hidden_size", 768)
+    num_layers = get(config, "num_hidden_layers", 12)
+    num_heads = get(config, "num_attention_heads", 12)
+    intermediate_size = get(config, "intermediate_size", 3072)
+    vocab_size = get(config, "vocab_size", 30522)
     head_dim = hidden_size ÷ num_heads
 
     @info "Building BERT model" hidden_size num_layers num_heads vocab_size
@@ -330,10 +344,10 @@ end
 Build GPT-2 architecture.
 """
 function build_gpt2(config)
-    hidden_size = get(config, :n_embd, 768)
-    num_layers = get(config, :n_layer, 12)
-    vocab_size = get(config, :vocab_size, 50257)
-    max_seq_len = get(config, :n_positions, 1024)
+    hidden_size = get(config, "n_embd", 768)
+    num_layers = get(config, "n_layer", 12)
+    vocab_size = get(config, "vocab_size", 50257)
+    max_seq_len = get(config, "n_positions", 1024)
     intermediate_size = hidden_size * 4
 
     @info "Building GPT-2 model" hidden_size num_layers vocab_size
@@ -379,14 +393,14 @@ end
 Build Vision Transformer architecture.
 """
 function build_vit(config)
-    hidden_size = get(config, :hidden_size, 768)
-    num_layers = get(config, :num_hidden_layers, 12)
-    num_heads = get(config, :num_attention_heads, 12)
-    intermediate_size = get(config, :intermediate_size, 3072)
-    image_size = get(config, :image_size, 224)
-    patch_size = get(config, :patch_size, 16)
-    num_channels = get(config, :num_channels, 3)
-    num_labels = get(config, :num_labels, 1000)
+    hidden_size = get(config, "hidden_size", 768)
+    num_layers = get(config, "num_hidden_layers", 12)
+    num_heads = get(config, "num_attention_heads", 12)
+    intermediate_size = get(config, "intermediate_size", 3072)
+    image_size = get(config, "image_size", 224)
+    patch_size = get(config, "patch_size", 16)
+    num_channels = get(config, "num_channels", 3)
+    num_labels = get(config, "num_labels", 1000)
 
     num_patches = (image_size ÷ patch_size)^2
 
@@ -421,12 +435,12 @@ Build ResNet architecture.
 """
 function build_resnet(config)
     # ResNet config may use different key names depending on HF model card
-    num_channels = get(config, :num_channels, 3)
-    num_labels = get(config, :num_labels, 1000)
+    num_channels = get(config, "num_channels", 3)
+    num_labels = get(config, "num_labels", 1000)
 
     # Detect ResNet variant from config
-    depths = get(config, :depths, [3, 4, 6, 3])  # ResNet-50 default
-    hidden_sizes = get(config, :hidden_sizes, [256, 512, 1024, 2048])
+    depths = get(config, "depths", [3, 4, 6, 3])  # ResNet-50 default
+    hidden_sizes = get(config, "hidden_sizes", [256, 512, 1024, 2048])
 
     @info "Building ResNet model" depths hidden_sizes
 
@@ -467,13 +481,13 @@ end
 Build LLaMA architecture (decoder-only transformer with RMSNorm and SwiGLU MLP).
 """
 function build_llama(config)
-    hidden_size = get(config, :hidden_size, 4096)
-    num_layers = get(config, :num_hidden_layers, 32)
-    num_heads = get(config, :num_attention_heads, 32)
-    intermediate_size = get(config, :intermediate_size, 11008)
-    vocab_size = get(config, :vocab_size, 32000)
+    hidden_size = get(config, "hidden_size", 4096)
+    num_layers = get(config, "num_hidden_layers", 32)
+    num_heads = get(config, "num_attention_heads", 32)
+    intermediate_size = get(config, "intermediate_size", 11008)
+    vocab_size = get(config, "vocab_size", 32000)
     # num_key_value_heads for GQA (defaults to num_heads for MHA)
-    num_kv_heads = get(config, :num_key_value_heads, num_heads)
+    num_kv_heads = get(config, "num_key_value_heads", num_heads)
 
     @info "Building LLaMA model" hidden_size num_layers num_heads num_kv_heads vocab_size
 
@@ -513,15 +527,15 @@ end
 Build Whisper architecture (encoder-decoder transformer for speech recognition).
 """
 function build_whisper(config)
-    d_model = get(config, :d_model, 512)
-    encoder_layers = get(config, :encoder_layers, 6)
-    decoder_layers = get(config, :decoder_layers, 6)
-    encoder_attention_heads = get(config, :encoder_attention_heads, 8)
-    decoder_attention_heads = get(config, :decoder_attention_heads, 8)
-    encoder_ffn_dim = get(config, :encoder_ffn_dim, 2048)
-    decoder_ffn_dim = get(config, :decoder_ffn_dim, 2048)
-    vocab_size = get(config, :vocab_size, 51865)
-    num_mel_bins = get(config, :num_mel_bins, 80)
+    d_model = get(config, "d_model", 512)
+    encoder_layers = get(config, "encoder_layers", 6)
+    decoder_layers = get(config, "decoder_layers", 6)
+    encoder_attention_heads = get(config, "encoder_attention_heads", 8)
+    decoder_attention_heads = get(config, "decoder_attention_heads", 8)
+    encoder_ffn_dim = get(config, "encoder_ffn_dim", 2048)
+    decoder_ffn_dim = get(config, "decoder_ffn_dim", 2048)
+    vocab_size = get(config, "vocab_size", 51865)
+    num_mel_bins = get(config, "num_mel_bins", 80)
 
     @info "Building Whisper model" d_model encoder_layers decoder_layers vocab_size
 
@@ -632,7 +646,7 @@ function _load_safetensors!(model, path::String)
     data = read(path)
     header_size = reinterpret(UInt64, data[1:8])[1]
     header_json = String(data[9:8+header_size])
-    header = JSON3.read(header_json)
+    header = JSON.parse(header_json)
     tensor_data_start = 8 + header_size
 
     # Build name → array mapping
@@ -641,9 +655,9 @@ function _load_safetensors!(model, path::String)
         name_str = String(name)
         name_str == "__metadata__" && continue
 
-        dtype_str = String(meta.dtype)
-        shape = Tuple(meta.shape)
-        offsets = meta.data_offsets  # [start, end] relative to tensor data
+        dtype_str = String(meta["dtype"])
+        shape = Tuple(meta["shape"])
+        offsets = meta["data_offsets"]  # [start, end] relative to tensor data
 
         # Parse dtype
         T = _safetensors_dtype(dtype_str)
@@ -731,7 +745,7 @@ function _set_layer_param!(layer, param_name::Symbol, data::Array)
 end
 
 function _load_json_weights!(model, path::String)
-    data = JSON3.read(read(path, String))
+    data = JSON.parse(read(path, String))
     tensors = Dict{String, Array}()
     for (name, tensor_data) in pairs(data)
         if tensor_data isa AbstractVector

test/integrations/huggingface_tests.jl

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MPL-2.0
+# Offline HuggingFace-integration tests (G06).
+#
+# Exercises the network-free core of `Axiom.HuggingFaceCompat`: architecture
+# detection, model building from a config Dict, SafeTensors dtype mapping, and
+# the pure verification report. The hub-fetch path
+# (`from_pretrained`/`get_model_info`/`download_file`) needs network and is
+# intentionally NOT exercised here — documented in the module header.
+
+using Test
+using Axiom
+
+const HF = Axiom.HuggingFaceCompat
+
+@testset "HuggingFace integration (offline)" begin
+
+    @testset "detect_architecture" begin
+        @test HF.detect_architecture(Dict("model_type" => "bert")) == "bert"
+        @test HF.detect_architecture(Dict("architectures" => ["GPT2LMHeadModel"])) == "GPT2LMHeadModel"
+        @test HF.detect_architecture(Dict("num_hidden_layers" => 12,
+                                          "num_attention_heads" => 12)) == "transformer"
+        @test HF.detect_architecture(Dict{String,Any}()) == "unknown"
+    end
+
+    @testset "build_model_from_config" begin
+        bert_cfg = Dict("hidden_size" => 128, "num_hidden_layers" => 2,
+                        "num_attention_heads" => 4, "intermediate_size" => 256,
+                        "vocab_size" => 1000)
+        bert = HF.build_model_from_config(bert_cfg, "bert")
+        @test bert isa Axiom.Pipeline
+        # 1 embedding + 2*(2 LayerNorm + 4 Dense + 2 Dense) + 1 pooler = 18
+        @test length(bert.layers) == 18
+
+        gpt2_cfg = Dict("n_embd" => 64, "n_layer" => 2, "vocab_size" => 500,
+                        "n_positions" => 128)
+        gpt2 = HF.build_model_from_config(gpt2_cfg, "gpt2")
+        @test gpt2 isa Axiom.Pipeline
+        # 1 embedding + 2*(2 LayerNorm + 3 Dense) + final LayerNorm + head = 13
+        @test length(gpt2.layers) == 13
+
+        # Unknown architecture falls back to the generic (BERT-shaped) builder.
+        gen = HF.build_model_from_config(bert_cfg, "totally-unknown-arch")
+        @test gen isa Axiom.Pipeline
+    end
+
+    @testset "SafeTensors dtype mapping" begin
+        @test HF._safetensors_dtype("F32") === Float32
+        @test HF._safetensors_dtype("F16") === Float16
+        @test HF._safetensors_dtype("F64") === Float64
+        @test HF._safetensors_dtype("I32") === Int32
+        @test HF._safetensors_dtype("I64") === Int64
+        @test HF._safetensors_dtype("BF16") === nothing   # BFloat16 not native in Julia
+        @test HF._safetensors_dtype("NOPE") === nothing   # unsupported dtype
+    end
+
+    @testset "verify_imported_model (pure, no network)" begin
+        bert = HF.build_model_from_config(
+            Dict("hidden_size" => 32, "num_hidden_layers" => 1,
+                 "num_attention_heads" => 2, "intermediate_size" => 64,
+                 "vocab_size" => 100), "bert")
+        report = HF.verify_imported_model(bert, "bert")
+        @test haskey(report, "passed")
+        @test haskey(report, "warnings")
+        @test haskey(report, "failures")
+        @test isempty(report["failures"])
+        # Secure default: remote-code execution is reported disabled unless the
+        # AXIOM_HF_TRUST_REMOTE_CODE env opt-in is set.
+        @test any(p -> occursin("Remote code execution disabled", p), report["passed"])
+    end
+
+    @testset "public API surface exists" begin
+        @test isdefined(HF, :from_pretrained)
+        @test isdefined(HF, :load_tokenizer)
+    end
+end

test/runtests.jl

@@ -761,6 +761,9 @@ with open(args.output, "w", encoding="utf-8") as f:
     include("e2e_test.jl")
     include("property_test.jl")
 
+    # HuggingFace integration — offline core (G06)
+    include("integrations/huggingface_tests.jl")
+
     # Quality gates (G07): static/dynamic analysis of Axiom's own code.
     include("aqua.jl")
     include("jet.jl")