refactor(interop): remove Python from_pytorch bridge, make it pure Julia (#63)

## Summary

The audit found `from_pytorch` claimed a **"built-in Python bridge"**
for direct `.pt/.pth/.ckpt` import — but the bridge script
(`scripts/pytorch_to_axiom_descriptor.py`) **never shipped**, so that
path always threw, and shelling out to `python3` violates the
estate-wide Python ban anyway.

This removes the Python entirely and makes PyTorch import **pure
Julia**.

## Changes

- **`src/integrations/interop.jl`** — delete `_run_pytorch_bridge` (the
`python3` shell-out) and `_default_pytorch_bridge_script`.
`from_pytorch(path; strict)` now imports the pure-Julia
`axiom.pytorch.sequential.v1` JSON descriptor. A raw `.pt/.pth/.ckpt`
gets a clear `ArgumentError` (it needs a PyTorch/Python runtime; export
the descriptor first) instead of a false "bridge" promise. The
`bridge`/`python_cmd`/`bridge_script` params are gone.
- **`test/runtests.jl` + `test/ci/interop_smoke.jl`** — the interop
tests previously **wrote an inline `.py` bridge script and ran it via
`python3`** (banned-language content in tests). Replaced with pure-Julia
descriptor tests: write the JSON descriptor directly, load it, and
assert a `.pt` path is rejected.
- **`ROADMAP.adoc` + `README.adoc`** — correct the two false `[x] direct
.pt bridge shipped (via scripts/pytorch_to_axiom_descriptor.py)` claims
and the "built-in Python bridge (requires python3 + torch)" README text
to the honest pure-Julia descriptor scope.

## Verification

- Package loads; `from_pytorch` **rejects `.pt` with `ArgumentError`**
and **imports the descriptor to a real `Pipeline`** (checked directly).
- `grep` confirms **no dangling references** to the removed bridge
params (`_run_pytorch_bridge`, `bridge_script`, `python_cmd`,
`AXIOM_PYTHON`, `pytorch_to_axiom_descriptor`) anywhere in `src/` or
`test/`.
- Full `Pkg.test()` matrix runs here as the authoritative gate.

## Not in this change (flagged)

`src/integrations/huggingface.jl:633` has a **help-string** suggesting
the user run `python -c "import torch; …"` to convert a `.bin` to
safetensors — not executed Python, a different feature. Left as-is
pending a call on whether to reword it.

A **native Julia checkpoint reader** (zip + pickle, to read raw `.pt`
without Python) is possible but needs a real `.pt` fixture to build
safely (which needs PyTorch) — noted as future work.

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

https://claude.ai/code/session_01UPFC9YQ7g9gc3VnRox42Q1

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

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

Author: hyperpolymath

README.adoc

@@ -96,20 +96,20 @@ save_certificate(cert, "fda_submission.cert")
 
 [source,julia]
 ----
-# Import from a PyTorch checkpoint (.pt/.pth/.ckpt) via built-in Python bridge
-# (requires python3 + torch in the selected runtime)
-model = from_pytorch("model.pt")
+# Import from a canonical PyTorch descriptor JSON — pure Julia, no runtime deps.
+model = from_pytorch("model.pytorch.json")
 
-# Or import canonical descriptor JSON
-model2 = from_pytorch("model.pytorch.json")
+# Raw .pt/.pth/.ckpt files are Python-pickle and need a PyTorch/Python runtime
+# to read, so they are not imported directly — export your model to the
+# `axiom.pytorch.sequential.v1` descriptor first, then import the .json above.
 
 # Export supported models to ONNX
 to_onnx(model, "model.onnx", input_shape=(1, 3, 224, 224))
 ----
 
 Current scope:
 
-* `from_pytorch(…)`: canonical descriptor import + direct `.pt/.pth/.ckpt` bridge.
+* `from_pytorch(…)`: pure-Julia `axiom.pytorch.sequential.v1` descriptor import.
 * `to_onnx(…)`: export for `Sequential`/`Pipeline` models built from
   Dense/Conv/Norm/Pool + common activations.
 
@@ -193,8 +193,7 @@ generate_grpc_proto("axiom_inference.proto")
 
 [source,julia]
 ----
-# PyTorch import (checkpoint bridge or canonical descriptor JSON)
-model = from_pytorch("model.pt")
+# PyTorch import — pure-Julia descriptor JSON (export from PyTorch first)
 model = from_pytorch("model.pytorch.json")
 
 # ONNX export (Dense/Conv/Norm/Pool + common activations)

ROADMAP.adoc

@@ -44,7 +44,7 @@ Must progress snapshot (2026-02-16):
 * [x] Added non-GPU accelerator strategy checks and CI coverage: `test/ci/coprocessor_strategy.jl`.
 * [x] Added certificate integrity CI checks and digest-report artifacts: `test/ci/certificate_integrity.jl`, `.github/workflows/verify-certificates.yml`.
 * [x] Added in-tree gRPC unary protobuf binary-wire support (`application/grpc`) with JSON bridge fallback (`application/grpc+json`).
-* [x] Added direct `.pt/.pth/.ckpt` import bridge and expanded ONNX export coverage (Dense/Conv/Norm/Pool + activations).
+* [x] Added pure-Julia PyTorch **descriptor** import (`axiom.pytorch.sequential.v1`) and expanded ONNX export coverage (Dense/Conv/Norm/Pool + activations). (Direct `.pt/.pth/.ckpt` binary import is *not* shipped — it would need a PyTorch/Python runtime; export to the descriptor first.)
 * [x] Added consolidated readiness gate script for local/CI release checks: `scripts/readiness-check.sh`.
 * [x] Added REAL authenticating hybrid Ed448+Dilithium5 (ML-DSA-87) certificate
   signing (G01, opt-in): Rust `cdylib` shim in `crypto/` (`pqcrypto-dilithium`
@@ -88,7 +88,7 @@ Could completion gates:
 
 These roadmap promises are still tracked explicitly (with current delivery state):
 
-* [x] `from_pytorch(...)` import API (baseline shipped: descriptor import + direct `.pt/.pth/.ckpt` bridge + CI interop smoke via `scripts/pytorch_to_axiom_descriptor.py`).
+* [x] `from_pytorch(...)` import API (shipped: pure-Julia `axiom.pytorch.sequential.v1` descriptor import + CI interop smoke). Direct binary `.pt/.pth/.ckpt` import is out of scope (needs a PyTorch/Python runtime); a native Julia checkpoint reader (zip + pickle) is future work.
 * [x] `to_onnx(...)` export API (baseline shipped: Dense/Conv/Norm/Pool + common activations for supported `Sequential`/`Pipeline` models).
 * [x] Production-hardened GPU paths across CUDA/ROCm/Metal (baseline shipped: deterministic fallback CI + optional hardware smoke + extension-hook dispatch + device-range guards + runtime self-healing diagnostics + backend-specific performance evidence via `test/ci/gpu_resilience.jl` and `scripts/gpu-performance-evidence.jl`).
 * [ ] Non-GPU accelerators (TPU/NPU/PPU/MATH/FPGA/DSP) backend strategy (in progress: targets, detection, compiled dispatch, fallback/strategy CI, capability/evidence reporting, runtime self-healing diagnostics, resilience CI/evidence, and TPU/NPU/DSP/MATH strict-mode gating shipped via `coprocessor_capability_report`, `coprocessor_runtime_diagnostics`, `scripts/coprocessor-evidence.jl`, `test/ci/coprocessor_resilience.jl`, `scripts/coprocessor-resilience-evidence.jl`, `test/ci/tpu_required_mode.jl`, `scripts/tpu-strict-evidence.jl`, `test/ci/npu_required_mode.jl`, `scripts/npu-strict-evidence.jl`, `test/ci/dsp_required_mode.jl`, `scripts/dsp-strict-evidence.jl`, `test/ci/math_required_mode.jl`, and `scripts/math-strict-evidence.jl`; production kernels remain).

src/integrations/interop.jl

@@ -93,54 +93,13 @@ function _nested_array_f32(value, field_name::AbstractString)
     _array_from_row_major(flat, shape)
 end
 
-function _default_pytorch_bridge_script()
-    normpath(joinpath(@__DIR__, "..", "..", "scripts", "pytorch_to_axiom_descriptor.py"))
-end
-
-function _run_pytorch_bridge(
-    input_path::AbstractString;
-    python_cmd::AbstractString = get(ENV, "AXIOM_PYTHON", "python3"),
-    bridge_script::AbstractString = _default_pytorch_bridge_script(),
-    strict::Bool = true,
-)
-    isfile(input_path) || throw(ArgumentError("Checkpoint path does not exist: $(input_path)"))
-    isfile(bridge_script) || throw(ArgumentError("PyTorch bridge script not found: $(bridge_script)"))
-
-    parts = Base.shell_split(String(python_cmd))
-    isempty(parts) && throw(ArgumentError("`python_cmd` must not be empty"))
-
-    tmp_path, tmp_io = mktemp()
-    close(tmp_io)
-    tmp_json_path = tmp_path * ".pytorch.json"
-    mv(tmp_path, tmp_json_path; force=true)
-
-    cmd_parts = copy(parts)
-    append!(cmd_parts, [
-        String(bridge_script),
-        "--input", String(input_path),
-        "--output", String(tmp_json_path),
-        strict ? "--strict" : "--no-strict",
-    ])
-    cmd = Cmd(cmd_parts)
-
-    stdout_buf = IOBuffer()
-    stderr_buf = IOBuffer()
-    ok = success(pipeline(cmd; stdout=stdout_buf, stderr=stderr_buf))
-    if !ok
-        stderr_out = String(take!(stderr_buf))
-        stdout_out = String(take!(stdout_buf))
-        rm(tmp_json_path; force=true)
-        throw(ErrorException(
-            "PyTorch bridge failed for `$(input_path)`.\n" *
-            "Command: $(cmd)\n" *
-            (isempty(stdout_out) ? "" : "stdout:\n$(stdout_out)\n") *
-            (isempty(stderr_out) ? "" : "stderr:\n$(stderr_out)\n")
-        ))
-    end
-
-    isfile(tmp_json_path) || throw(ErrorException("PyTorch bridge did not produce descriptor output: $(tmp_json_path)"))
-    tmp_json_path
-end
+# PyTorch import is pure Julia: `from_pytorch` reads the
+# `axiom.pytorch.sequential.v1` JSON descriptor directly (see below). The
+# previous bridge shelled out to a `python3` script to convert raw
+# `.pt/.pth/.ckpt` checkpoints — removed, because Python is banned estate-wide
+# and that bridge script never shipped (so the "direct checkpoint" path always
+# failed anyway). Reading a raw checkpoint (zip + pickle) natively in Julia is
+# tracked as future work; today, export the model to the descriptor first.
 
 function _pytorch_layers(spec::Dict{String, Any})
     raw_layers = get(spec, "layers", get(spec, "modules", nothing))
@@ -373,54 +332,33 @@ function _pytorch_module_to_layer(spec::Dict{String, Any}; strict::Bool = true)
 end
 
 """
-    from_pytorch(path::AbstractString; strict=true, bridge=true, python_cmd="python3", bridge_script=scripts/pytorch_to_axiom_descriptor.py)
-
-Import a model from:
-- a PyTorch JSON descriptor (`axiom.pytorch.sequential.v1`)
-- or a `.pt`/`.pth`/`.ckpt` checkpoint via the built-in Python bridge script.
+    from_pytorch(path::AbstractString; strict=true)
 
-Bridge requirements for direct checkpoints:
-- Python runtime (`python3` by default, configurable via `python_cmd`)
-- `torch` installed in that Python environment
+Import a model from a PyTorch **JSON descriptor** (`axiom.pytorch.sequential.v1`).
+Pure Julia — no Python runtime, no external bridge.
 
 Supported descriptor format:
 - `format = "axiom.pytorch.sequential.v1"`
 - `layers = [...]` where each layer is a module object (`Linear`, `ReLU`, etc.)
+
+Raw `.pt`/`.pth`/`.ckpt` checkpoints are **not** loaded directly (that would
+require a PyTorch/Python runtime, which is out of scope). Export the model to
+the descriptor format first, then pass the resulting `.json` here.
 """
-function from_pytorch(
-    path::AbstractString;
-    strict::Bool = true,
-    bridge::Bool = true,
-    python_cmd::AbstractString = get(ENV, "AXIOM_PYTHON", "python3"),
-    bridge_script::AbstractString = _default_pytorch_bridge_script(),
-)
+function from_pytorch(path::AbstractString; strict::Bool = true)
     isfile(path) || throw(ArgumentError("PyTorch import path does not exist: $(path)"))
     ext = lowercase(splitext(String(path))[2])
 
     if ext in (".pt", ".pth", ".ckpt")
-        bridge || throw(ArgumentError(
-            "Direct `.pt/.pth/.ckpt` loading requires bridge support. " *
-            "Pass `bridge=true` (default) or export JSON descriptor first."
+        throw(ArgumentError(
+            "Direct `.pt/.pth/.ckpt` import is not supported (it needs a " *
+            "PyTorch/Python runtime). Export the model to the " *
+            "`axiom.pytorch.sequential.v1` JSON descriptor and pass that `.json` " *
+            "to `from_pytorch` instead."
         ))
-        descriptor_path = _run_pytorch_bridge(
-            path;
-            python_cmd=python_cmd,
-            bridge_script=bridge_script,
-            strict=strict
-        )
-        try
-            return from_pytorch(descriptor_path; strict=strict, bridge=false)
-        finally
-            rm(descriptor_path; force=true)
-        end
-    end
-
-    spec = try
-        JSON.parse(read(path, String))
-    catch e
-        rethrow(e)
     end
 
+    spec = JSON.parse(read(path, String))
     from_pytorch(spec; strict=strict)
 end
 

test/ci/interop_smoke.jl

@@ -61,45 +61,22 @@ Random.seed!(0xA710)
 
     pt_path = tempname() * ".pth"
     write(pt_path, "placeholder")
-    @test_throws ArgumentError from_pytorch(pt_path; bridge=false)
+    # Raw .pt/.pth/.ckpt import is unsupported (needs a PyTorch/Python runtime).
+    @test_throws ArgumentError from_pytorch(pt_path)
 
-    bridge_script = tempname() * ".py"
-    open(bridge_script, "w") do io
-        write(io, """
-import argparse
-import json
-
-p = argparse.ArgumentParser()
-p.add_argument("--input", required=True)
-p.add_argument("--output", required=True)
-p.add_argument("--strict", action="store_true")
-p.add_argument("--no-strict", action="store_false", dest="strict")
-args = p.parse_args()
-
-spec = {
-  "format": "axiom.pytorch.sequential.v1",
-  "layers": [
+    # Pure-Julia descriptor import — no Python, no external bridge.
+    descriptor_path = tempname() * ".pytorch.json"
+    write(descriptor_path, """
     {
-      "type": "Linear",
-      "in_features": 3,
-      "out_features": 2,
-      "weight": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
-      "bias": [0.0, 0.0]
-    },
-    {"type": "ReLU"}
-  ]
-}
-
-with open(args.output, "w", encoding="utf-8") as f:
-    json.dump(spec, f)
-""")
-    end
-    bridged = from_pytorch(
-        pt_path;
-        python_cmd="python3",
-        bridge_script=bridge_script,
-        strict=true
-    )
+      "format": "axiom.pytorch.sequential.v1",
+      "layers": [
+        {"type": "Linear", "in_features": 3, "out_features": 2,
+         "weight": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]], "bias": [0.0, 0.0]},
+        {"type": "ReLU"}
+      ]
+    }
+    """)
+    bridged = from_pytorch(descriptor_path; strict=true)
     @test bridged isa Axiom.Pipeline
 
     cv_model = Sequential(
@@ -129,7 +106,7 @@ with open(args.output, "w", encoding="utf-8") as f:
     rm(spec_path)
     rm(onnx_path)
     rm(pt_path)
-    rm(bridge_script)
+    rm(descriptor_path)
     rm(cv_onnx_path_a)
     rm(cv_onnx_path_b)
 end

test/runtests.jl

@@ -604,45 +604,24 @@ using JSON
 
         pt_path = tempname() * ".pth"
         write(pt_path, "placeholder")
-        @test_throws ArgumentError from_pytorch(pt_path; bridge=false)
-
-        bridge_script = tempname() * ".py"
-        open(bridge_script, "w") do io
-            write(io, """
-import argparse
-import json
-
-p = argparse.ArgumentParser()
-p.add_argument("--input", required=True)
-p.add_argument("--output", required=True)
-p.add_argument("--strict", action="store_true")
-p.add_argument("--no-strict", action="store_false", dest="strict")
-args = p.parse_args()
-
-spec = {
-  "format": "axiom.pytorch.sequential.v1",
-  "layers": [
-    {
-      "type": "Linear",
-      "in_features": 3,
-      "out_features": 2,
-      "weight": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
-      "bias": [0.0, 0.0]
-    },
-    {"type": "ReLU"}
-  ]
-}
-
-with open(args.output, "w", encoding="utf-8") as f:
-    json.dump(spec, f)
-""")
-        end
-        bridged = from_pytorch(
-            pt_path;
-            python_cmd="python3",
-            bridge_script=bridge_script,
-            strict=true
-        )
+        # Raw .pt/.pth/.ckpt import is not supported (it would need a PyTorch/
+        # Python runtime); from_pytorch rejects it with a clear message.
+        @test_throws ArgumentError from_pytorch(pt_path)
+
+        # Pure-Julia descriptor import: write the axiom.pytorch.sequential.v1
+        # JSON descriptor directly and load it — no Python, no external bridge.
+        descriptor_path = tempname() * ".pytorch.json"
+        write(descriptor_path, """
+        {
+          "format": "axiom.pytorch.sequential.v1",
+          "layers": [
+            {"type": "Linear", "in_features": 3, "out_features": 2,
+             "weight": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]], "bias": [0.0, 0.0]},
+            {"type": "ReLU"}
+          ]
+        }
+        """)
+        bridged = from_pytorch(descriptor_path; strict=true)
         @test bridged isa Axiom.Pipeline
 
         cv_model = Sequential(
@@ -672,7 +651,7 @@ with open(args.output, "w", encoding="utf-8") as f:
         rm(spec_path)
         rm(onnx_path)
         rm(pt_path)
-        rm(bridge_script)
+        rm(descriptor_path)
         rm(cv_onnx_path_a)
         rm(cv_onnx_path_b)
     end