onnxify

name: onnxify description: "Use this skill when working with the public Onnxify package family in this repository: Onnxify for loading, inspecting, creating, editing, and saving ONNX models; Onnxify.TorchSharp for exporting TorchSharp modules to ONNX; Onnxify.Safetensors for safetensors archives and tensor storage; Onnxify.HuggingFace for downloading selected Hugging Face model repository files; Onnxify.ProjectGenerator for generating C# reconstruction projects from existing .onnx files; Onnxify.ModelGenerator for generating typed Microsoft.ML.OnnxRuntime wrappers from .onnx files; and Onnxify.ML / Onnxify.ML.TorchSharp for inference and training pipelines. Use it to choose the right package, implement or review behavior, and validate examples and tests across src/Onnxify*, src/Onnxify.Tests, src/Onnxify.ConsoleTest, and src/Onnxify.Examples."

Onnxify

Overview

Use this skill for repository-specific work on Onnxify rather than generic ONNX advice. It is tuned for the object model in src/Onnxify, the TorchSharp export layer in src/Onnxify.TorchSharp, the current tests in src/Onnxify.Tests, and the example/playground projects in src/Onnxify.ConsoleTest and src/Onnxify.Examples.

Read references/api-surface.md when you need concrete entry points, TorchSharp export files, example model locations, or a quick reminder of which project to touch. Read references/cli.md when you need to inspect .onnx or .safetensors files from the terminal, view only model inputs/outputs, generate a C# project from an ONNX file, or download selected Hugging Face repository files. Read references/inference-from-onnx.md when you are asked to build C# inference code for an existing .onnx model using Microsoft.ML.OnnxRuntime. Read references/model-generator.md when you need to consume an existing .onnx file through generated, strongly typed Microsoft.ML.OnnxRuntime wrappers from the Onnxify.ModelGenerator NuGet package. Read references/safetensors.md when the task is about reading, writing, inspecting, slicing, or TorchSharp state-dict round-tripping with Onnxify.Safetensors. Read references/onnxify-graph-examples.md when you need example-driven guidance for building ONNX graphs directly with Onnxify, including model authoring from scratch, additive graph edits, and strongly typed operator wrappers. Read references/torchsharp-export-examples.md when you need example-driven guidance for structuring a TorchSharp model and its custom Export() method so the ONNX graph mirrors the model's real computation. Read references/ml-pipelines.md when you need to build, explain, extend, or review Onnxify.ML or Onnxify.ML.TorchSharp inference and training pipelines. Read references/operators/index.md when the task is operator-specific and you need the autogenerated wrapper signature, schema-driven parameter descriptions, or current Onnxify.TorchSharp converter coverage for a specific ONNX operator. Read references/torchsharp-converters/index.md when the task is about the public Onnxify.TorchSharp conversion signatures themselves and you want the generated Export(...) overload catalog by TorchSharp module type.

Quick Start

When handling an Onnxify task:

1. Identify the task shape: core model load/save, graph editing, operator wrapper work, TorchSharp export work, project generation, or examples/tests.
2. Decide which layer owns the behavior before editing. Put raw ONNX graph concerns in src/Onnxify; put TorchSharp-to-ONNX translation in src/Onnxify.TorchSharp.
3. Read the closest production type first, usually OnnxModel, OnnxGraph, OnnxNode, OnnxTensor, OnnxValue, or the relevant TorchSharp Export(...) extension.
4. Read an existing test or example before changing behavior. Prefer src/Onnxify.Tests for semantics and src/Onnxify.Examples for end-to-end export patterns.
5. Make the smallest repo-consistent change.
6. Validate with focused tests. Prefer round-trip coverage for serialization changes and structure-preserving checks for TorchSharp export changes.
7. If the task is about a specific operator surface, use the autogenerated operator docs first, then inspect the underlying implementation.

Core Principles

• Treat Onnxify as the source of truth for ONNX object modeling, graph structure, and protobuf round-tripping.
• Treat Onnxify.TorchSharp as an export adapter layer that translates TorchSharp modules into OnnxGraph operations; do not move generic graph concerns into that layer.
• Preserve the lightweight wrapper model over generated protobuf types instead of introducing a second parallel object model.
• Prefer explicit graphs, explicit names, and explicit tensor/value types over hidden conventions or reflection-heavy magic unless the existing export layer already relies on that pattern.
• Reject unsupported semantics loudly with NotSupportedException or NotImplementedException instead of emitting a lossy or silently wrong graph.

NuGet Package Map

Use this section for the packages and tools that the repo itself exports outward, not for the third-party packages the repo consumes internally. The list below is inferred from the current *.csproj pack metadata plus the repo's README.md package plan.

• Onnxify (src/Onnxify): the main public library for loading, inspecting, creating, editing, and saving ONNX models through the repo's wrapper object model over protobuf-generated ONNX types.
• Onnxify.TorchSharp (src/Onnxify.TorchSharp): the public TorchSharp-to-ONNX export adapter layer. Use this when the task is about translating TorchSharp modules into OnnxGraph operations or extending Export(...) coverage.
• Onnxify.Safetensors (src/Onnxify.Safetensors): the public safetensors-focused library for reading metadata, indexing tensor slices, and working with safetensors-backed tensor storage; treat it as the repo's dedicated safetensors surface.
• Onnxify.ProjectGenerator (src/Onnxify.ProjectGenerator): the public project/code generation library that takes an existing ONNX model and emits a C# project or program that reconstructs that model with Onnxify.
• Onnxify.ModelGenerator (src/Onnxify.ModelGenerator): the public Roslyn source-generator package that turns .onnx files in a consuming project into typed Microsoft.ML.OnnxRuntime wrapper classes with generated input/output contracts.
• Onnxify.ML (src/Onnxify.ML): the public typed pipeline foundation for ML workflows. Use it for batching, branching, orchestration, progress reporting, and reusable runtime stages that are not TorchSharp-specific.
• Onnxify.ML.TorchSharp (src/Onnxify.ML.TorchSharp): the public TorchSharp-oriented pipeline layer. Use it for tensor collation, TorchSharp inference stages, and TorchSharp training-step orchestration inside Onnxify.ML pipelines.
• Onnxify.HuggingFace (src/Onnxify.HuggingFace): the public Hugging Face model repository download client. Use it to download repository files into a local directory with revision, access-token, include/exclude path filters, and progress callbacks.
• Onnxify.CLI (src/Onnxify.CLI): a publishable dotnet tool, not a normal library package. It exposes the onnxify command for inspecting ONNX files and driving repo workflows such as project generation and Hugging Face downloads.

Package Boundary Notes

• When the user asks about "the NuGet package" for core ONNX graph/object-model work, default to Onnxify.
• When the user asks about exporting TorchSharp models to ONNX, default to Onnxify.TorchSharp.
• When the user asks about generating C# from an existing .onnx file, default to Onnxify.ProjectGenerator or the Onnxify.CLI tool depending on whether they want an API or a command-line workflow.
• When the user asks about generating a typed runtime wrapper around an existing .onnx file for Microsoft.ML.OnnxRuntime, default to Onnxify.ModelGenerator.
• When the user asks about reusable ML workflow composition, training loops, inference pipelines, batching, branching, or progress-aware orchestration, default to Onnxify.ML and Onnxify.ML.TorchSharp.
• When the user asks about downloading model files from Hugging Face, default to Onnxify.HuggingFace for library code or Onnxify.CLI for terminal usage. Prefer include/exclude filters for large multi-variant repositories instead of downloading every file by default.
• Do not treat src/Onnxify.Tests, src/Onnxify.Examples, src/Onnxify.ConsoleTest, src/Onnxify.AgentSkillGenerator, or src/Onnxify.TorchSharp.Observer as external NuGet surfaces.
• src/Onnxify.SourceGenerator is currently better treated as an internal build/generator implementation detail than as a documented standalone package surface for end users.

1. Loading And Inspecting Models

• Start with OnnxModel.FromFile(path) for existing models.
• Use await OnnxModel.FromFileAsync(path, cancellationToken: ...) when file I/O should not block the caller.
• Use OnnxModel.FromStream(stream) or await OnnxModel.FromStreamAsync(stream, cancellationToken: ...) when the model already comes from memory, a network response, embedded resources, or another stream source. Set OnnxModelBaseOptions.DataLocation when relative external tensor data still needs a filesystem base path.
• Inspect through model.Graph, then walk Inputs, Outputs, Initializers, IntermediateValues, and Nodes.
• Prefer repository terminology: graph values may be inputs, outputs, placeholders, initializers, or loose edges.
• If you only need to inspect structure, avoid rewriting the model unless the task requires it.

2. Creating Or Editing Models

• Create new models with OnnxModel.Create(new OnnxModelCreationOptions { ... }).
• OnnxModel.Create() defaults to standard ONNX opset 25 and IR version 11. Treat these as the current Onnxify ONNX baseline versions: opset 25 comes from the bundled standard-domain operator schemas, and IR version 11 is the repository compatibility target for generated models. Use explicit OnnxModelCreationOptions.Opset and IrVersion when a model must target an older runtime profile.
• Add graph members through AddInput, AddOutput, AddValue, AddTensor, AddEdge, and AddNode.
• Promote an existing OnnxValue to a public contract with AddInput(OnnxValue) or AddOutput(OnnxValue), and reverse that public-contract marker with RemoveInput(...) or RemoveOutput(...) without deleting the value metadata itself.
• Remove or replace graph members with RemoveNode(...), ReplaceNode(...), RemoveValue(...), ReplaceValue(...), RemoveTensor(...), and RemoveEdge(...). Removal helpers clear matching node input/output references and prune unused loose edges so edited graphs do not keep dangling graph pieces.
• Respect unique-name constraints. The graph helpers throw on duplicates, so preserve stable names when patching an existing graph.
• Use graph.NextName(prefix) when generating new operator or edge names instead of inventing a parallel naming scheme.
• When a task is operator-oriented, prefer existing typed helpers or wrapper classes over raw AddNode if the repository already exposes them.
• When no helper exists yet, implement behavior in the most local, consistent layer instead of introducing a parallel abstraction.
• Keep edge, tensor, and placeholder wiring explicit. In this repo, graph construction is not hidden behind an optimizer or execution tracer.

2A. Onnxify Principles

• Keep OnnxModel responsible for file I/O, top-level metadata, and protobuf conversion.
• Keep OnnxGraph responsible for owned collections and graph mutation: inputs, outputs, values, initializers, edges, and nodes.
• Prefer preserving names and metadata when editing an existing model. Avoid accidental renames that break downstream graph references.
• When changing tensor or attribute conversion behavior, inspect helpers under src/Onnxify/Helpers and data types under src/Onnxify/Data before patching call sites.
• When adding new operator wrappers, match the repo's style of strongly named option objects and explicit input/output edges.

2B. Onnxify.TorchSharp Principles

• Onnxify.TorchSharp currently references TorchSharp 0.107.0; examples that add TorchSharp-cpu or a CUDA runtime package should use the matching TorchSharp runtime version unless the project has intentionally moved to a newer dependency.
• Treat TorchSharp export as inference-oriented graph synthesis, not as runtime tracing or training-time execution.
• Prefer implementing support as Export(...) extension methods on concrete TorchSharp module types in TorchModuleExtensions.cs.
• Keep TorchModule.Export(graph, input) as the public dispatch entry point and extend its module switch consistently when adding support.
• Materialize weights, biases, and constants through graph.AddTensor(...) using TorchHelper conversions instead of embedding ad hoc tensor-reading logic everywhere.
• Normalize TorchSharp-specific shapes and options into ONNX form inside the export layer. Existing examples include padding expansion, pool/resize normalization, and LSTM gate reordering.
• Preserve semantic mismatches explicitly. If ONNX and TorchSharp conventions differ, encode the conversion in one place and document it with a concise comment if the mapping is non-obvious.
• Keep complex export helpers local to the export layer or example model that owns them. Do not push example-specific graph composition into the core library unless it is broadly reusable.
• Prefer examples in src/Onnxify.Examples when demonstrating composed export pipelines, especially for Sequential, Embedding, LayerNorm, LSTM, attention blocks, or tied-weight projections.
• Remember that some exports are intentionally constrained to inference-safe cases. Existing code rejects unsupported training-mode or missing-statistics scenarios instead of guessing.

3. Serialization And Round Trips

• Save models with model.Save(path, overwrite: ...).
• In async workflows, save with await model.SaveAsync(path, overwrite: ..., cancellationToken: ...).
• For non-file destinations, use model.Save(stream) or await model.SaveAsync(stream, cancellationToken: ...).
• For any change that affects protobuf conversion, graph composition, or tensor/value metadata, add or update a round-trip test.
• Verify both structure and metadata after reload: producer info, IR/opset, graph members, attributes, tensor values, and node connections.
• Preserve DataLocation and path-sensitive behavior when touching tensor loading or external data logic.

4. Testing Strategy

• Put automated behavior checks in src/Onnxify.Tests.
• Use src/Onnxify.ConsoleTest only as a manual playground, not as proof that behavior is correct.
• Use src/Onnxify.Examples as a source of realistic export patterns, not as a replacement for focused assertions.
• Keep tests focused and deterministic. Temporary files are acceptable if cleaned up in finally.
• For generation features, assert on emitted file contents and output paths, as done in project generator tests.
• For TorchSharp export changes, assert graph structure and exported attributes instead of relying only on visual inspection or manual execution.
• When touching a complex exporter such as LSTM, cover the semantic translation points that are easy to regress: weight order, tensor shapes, batch/sequence layout, and optional outputs.

5. Project Conventions

• This repo is early-stage. Favor small extensions over large framework reshapes.
• Preserve the lightweight wrapper model over protobuf-generated ONNX classes.
• Match the existing C# style: explicit names, small helper methods, and straightforward Fact tests.
• If a project looks like a placeholder, avoid building new functionality there unless the user asked for that exact surface.
• Onnxify.TorchSharp is a real integration surface, but it should stay focused on translation glue rather than becoming a second general-purpose graph API.

Common Task Mapping

• Read or rewrite .onnx: start with src/Onnxify/OnnxModel.cs and related tests.
• Add graph members or wire nodes: start with src/Onnxify/OnnxGraph.cs.
• Need worked examples for direct Onnxify graph authoring, graph edits, or typed operator usage: read references/onnxify-graph-examples.md.
• Debug a node or attribute issue: inspect OnnxNode, OnnxAttribute, and a nearby round-trip test.
• Add or adjust higher-level operator APIs: inspect existing operator helper usage in tests and console examples first.
• Need per-operator wrapper or converter guidance: start with references/operators/index.md, then open the generated operator file for that exact domain and operator name.
• Need the public TorchSharp converter signatures or the Torch op names attached to each Export(...) overload: start with references/torchsharp-converters/index.md.
• Need worked examples that show how a TorchSharp model's forward(...) structure should map into a custom ONNX Export() method: read references/torchsharp-export-examples.md.
• Add or fix TorchSharp export support: start with src/Onnxify.TorchSharp/TorchModuleExtensions.cs.
• Adjust Torch tensor conversion helpers: inspect src/Onnxify.TorchSharp/TorchHelper.cs.
• Need Onnxify.Safetensors usage patterns or TorchSharp weight save/load examples: read references/safetensors.md.
• Need to build or explain training/inference pipelines: read references/ml-pipelines.md, then inspect src/Onnxify.Examples/Models/AlexNetTrainer.cs and src/Onnxify.Tests/OnnxifyPipelineTests.cs.
• Map a TorchSharp operator or module to an ONNX export surface: inspect TorchOpAttribute usage and nearby Export(...) implementations before designing a new pattern.
• Need a realistic export example: inspect src/Onnxify.Examples/Models/TorchSharpExportShowcase.cs, LSTMLIDModel.cs, or MiniGpt2LikeModel.cs.
• Need to refresh the generated skill docs after operator-wrapper or TorchSharp-export changes: run src/Onnxify.AgentSkillGenerator.
• Generate C# from a model: inspect src/Onnxify.ProjectGenerator.
• Generate typed OnnxRuntime wrappers from a model included in a consumer project: inspect src/Onnxify.ModelGenerator and read references/model-generator.md.
• Download selected model repository files from Hugging Face: inspect src/Onnxify.HuggingFace, use HuggingFaceClient.DownloadRepositoryAsync(...), and prefer IncludePath/ExcludePath filters for variants such as bf16.
• Need a fast no-code inspection, Hugging Face download, or project scaffold from a model file: use src/Onnxify.CLI and read references/cli.md.
• Need to write Microsoft.ML.OnnxRuntime inference code for an existing model file: read references/inference-from-onnx.md.
• Need a manual repro with real assets: inspect src/Onnxify.ConsoleTest/Assets and src/Onnxify.ConsoleTest/Program.cs.

Validation Checklist

• Did the change preserve existing naming and graph-linking behavior?
• Is there a focused automated test for the new or changed behavior?
• If serialization changed, did you verify save + load instead of only in-memory state?
• If TorchSharp export changed, did you verify the ONNX graph structure that gets emitted, not only that the source module still runs?
• If the export relies on module internals or reflection, did you keep the lookup localized and fail clearly when TorchSharp metadata is missing?
• If ONNX semantics differ from TorchSharp semantics, did you encode the translation explicitly and check the resulting tensor layout or attributes?
• If the task touched examples or playground code only, did you avoid silently changing library semantics?