Inspiration
Understanding an open-weight AI model should not require manually piecing together configuration files, source code, module hierarchies, checkpoint metadata, and documentation just to answer basic questions:
- What are the actual components of this model?
- How are they connected?
- Which tensors belong to which components?
- Where did a particular architectural fact come from?
- What can we confidently say when the available artifacts are incomplete?
Model hubs make it easy to discover and download models, but understanding the internal architecture of a specific model revision is still surprisingly manual. Architecture diagrams are often static, manually created, or disconnected from the artifacts that define the model.
We wanted to build something closer to an architecture debugger for open-weight models.
That led to Model Anatomy: a system that takes a specific model revision, inspects its available artifacts, reconstructs a semantic architecture representation, and lets engineers explore that structure with evidence and provenance attached to it.
The key design decision was to make evidence the foundation. If the system cannot establish something from the available artifacts, it should report that uncertainty rather than invent an attractive-looking answer.
What it does
Model Anatomy reconstructs and interactively explores the architecture of open-weight AI models.
A user provides a model identifier or URL. Model Anatomy then:
- Resolves and pins the specific model revision.
- Enumerates the available artifacts before analysis.
- Extracts architectural information from configuration, module structure, source code, model traces, and Safetensors metadata where available.
- Builds a Raw Architecture IR containing observed facts and their provenance.
- Converts those facts into a Semantic Architecture IR containing concepts such as embeddings, attention blocks, MLPs, normalization layers, repeated blocks, and custom components.
- Builds an interactive architecture graph from that representation.
- Lets engineers inspect nested components, tensors, parameter ownership, relationships, and evidence.
- Explicitly represents partial or unknown information instead of silently filling gaps.
The frontend renders the architecture representation produced by the backend rather than independently guessing the model structure.
Model Anatomy also provides an optional AI explanation layer using an NVIDIA model through Nebius. The AI receives selected evidence from the reconstructed architecture and explains it conversationally. It cannot create or modify architecture facts, and its citations and numerical claims are checked against the supplied evidence.
The result is a pipeline from:
model artifacts → evidence → architecture reconstruction → interactive inspection → evidence-bound explanation
How we built it
We designed Model Anatomy as an architecture reconstruction pipeline rather than a visualization wrapper.
The model resolver normalizes the requested model, pins the exact revision, and inventories the available artifacts. This gives each analysis a concrete source state instead of relying on an ambiguous "latest" model.
Multiple extractors collect different types of evidence:
- Model configuration
nn.Modulehierarchy- Source information
- Structural traces
- Safetensors/checkpoint metadata
These facts are first stored in a Raw Architecture IR, preserving what was actually observed and where it came from.
A second Semantic Architecture IR maps those facts into higher-level concepts such as attention, MLP, embedding, normalization, repeated blocks, and custom components.
The graph is generated from this IR and retains evidence-backed relationships. Different relationship types are represented explicitly rather than treating every connection as runtime tensor flow.
The backend is built with FastAPI and manages analyses, stored results, exports, quotas, and evidence-bound questions. Analysis work runs separately from the API in a bounded worker process.
The React/TypeScript frontend uses React Flow for interactive architecture graphs, with nested graphs loaded on demand. Components expose their attributes, tensors, parameter ownership, and provenance through the interface.
The optional AI layer uses an OpenAI-compatible NVIDIA model through Nebius. The model receives selected architecture evidence, and its structured response is validated before being returned. Citations must correspond to supplied evidence, and numerical claims are checked against the cited values.
The central architectural principle is:
Deterministic reconstruction first. AI explanation second.
Challenges we ran into
The hardest part was not drawing the graph. It was deciding what the graph is actually allowed to claim.
Model repositories are not uniform. Different models expose different combinations of configuration, source code, module structures, checkpoint metadata, and other artifacts. A system that assumes every model follows one clean architecture quickly becomes unreliable.
We therefore had to design around incomplete information.
One major challenge was provenance. It was not enough to say that a model contains an attention block; we wanted to preserve the evidence supporting that claim. This led to the separation between raw facts and semantic interpretation, with provenance carried through the reconstruction process.
Another challenge was avoiding false precision. When activation shapes or relationships could not be established from available evidence, the system needed to leave them unknown rather than fabricate them.
The AI layer introduced another challenge. An LLM can produce a convincing architectural explanation even when the underlying evidence does not support it. We therefore constrained the AI to the reconstructed evidence, required citations, validated its structured response, and checked numerical claims against the supplied evidence.
We also had to make the architecture explorer usable for large graphs without turning the interface into an unreadable diagram. Nested graphs, on-demand loading, layout, search, and component inspection became important parts of the implementation.
Accomplishments that we're proud of
The biggest accomplishment is that Model Anatomy became more than a model visualization layer.
We built a complete path from real model artifacts to an inspectable architecture representation, while preserving evidence throughout the process.
We are particularly proud of:
- Pinned model revisions, giving each analysis a concrete source state.
- Artifact-first analysis, rather than assuming a fixed model format.
- A two-stage Raw IR → Semantic IR architecture separating observed facts from higher-level interpretation.
- Evidence and provenance attached to architectural information, rather than treating the final diagram as the source of truth.
- Explicit handling of partial and unknown architecture information.
- Tensor and parameter ownership inspection alongside the architecture graph.
- A frontend that renders the backend's reconstructed representation instead of independently guessing model structure.
- An optional evidence-bound AI explanation layer using NVIDIA's model through Nebius.
- Validation that prevents the AI from introducing unsupported architecture facts or unchecked numerical claims.
Most importantly, we are proud of the product direction: the goal is not simply to make architecture diagrams prettier. It is to make them inspectable, traceable, and grounded in the actual artifacts of the model being analyzed.
What we learned
We learned that model understanding is fundamentally an evidence and representation problem, not just a visualization problem.
A model's architecture is distributed across multiple sources. Configuration tells us some things, source code tells us others, module structure exposes hierarchy, and checkpoint metadata can reveal tensor-level information. No single source is always sufficient.
We also learned that uncertainty needs to be treated as a first-class result.
It is tempting to infer what "should" be there based on common transformer conventions. But for an inspection tool, a plausible guess is worse than an explicit unknown. This shaped the architecture around provenance, evidence types, and partial results.
Another important lesson was about AI. LLMs are extremely useful for explaining technical structures, but they should not automatically become the source of truth for those structures.
For Model Anatomy, the architecture comes from deterministic analysis. The AI sits on top of that representation and explains what has already been established.
That distinction made the system substantially more trustworthy.
What's next for Model Anatomy
The current system establishes the foundation for a broader architecture intelligence layer for open-weight AI models.
Next, we want to expand artifact extractors and semantic reconstruction coverage so that more model families and unusual architectures can be analyzed without requiring model-specific assumptions.
We also want to make architecture comparison a first-class capability. Given two model revisions or two related models, users should be able to see exactly what changed in their components, tensors, configuration, and topology, with evidence for each difference.
Future directions include:
- Architecture diffing across model revisions
- Cross-model architecture comparison
- Deeper checkpoint and tensor analysis
- Broader support for custom model implementations
- Reusable architecture IRs for downstream tooling
- Stronger navigation from semantic components back to their source artifacts
- More powerful evidence-bound natural-language investigation
The long-term goal is to make Model Anatomy useful not only for understanding a model, but for answering deeper engineering questions about how models are structured, how they differ, and what the underlying artifacts actually prove.
Built With
- elk
- fastapi
- hugging-face
- nebius-token-factory
- nvidia
- postgresql
- python
- react
- react-flow
- safetensors
- typescript
- vite
