1 vin.diagnostics.model_inspection

vin.diagnostics.model_inspection

Inspect VIN configuration, registered model state, and bounded tensor samples.

The module returns rendering-neutral frozen records. Configuration inspection walks supported Pydantic structure without constructing its target; model inspection reads registered state without a forward pass; and numerical capture is an explicit hook context around the caller’s ordinary forward pass. Plotting, serialization, and interpretation of these records belong to downstream callers.

1.1 Classes

Name Description
CaptureLimits Positive quotas for one ModelCapture instance.
ConfigFieldSpec One field observed in a construction-free configuration walk.
ModelCapture Capture bounded tensors from registered module instances.
ModelMetadata Registered-module metadata for an already constructed model.
ModelStructureSpec Construction-free description of one model configuration tree.
ModuleMetadata Static metadata for one registered module in a constructed model.
TensorSnapshot Complete source metadata plus a detached, bounded tensor value sample.

1.1.1 CaptureLimits

vin.diagnostics.model_inspection.CaptureLimits(
    max_tensors=64,
    max_samples_per_tensor=32,
    max_bytes=16 * 1024,
    max_traversal_nodes=4096,
    max_container_depth=32,
)

Positive quotas for one ModelCapture instance.

Tensor-count and byte quotas are cumulative across every call and context entrance made with the instance. Traversal quotas restart for each module invocation’s combined positional/keyword inputs and separately for its output. These limits bound inspected nodes and copied numeric payload; they do not bound the source model, source tensors, hook metadata, Python record overhead, or total process/device memory.

1.1.1.1 Attributes

Name Description
max_tensors Maximum tensor snapshots retained across the capture instance.
max_samples_per_tensor Maximum row-major flattened elements copied from one source tensor.
max_bytes Maximum source-dtype bytes copied into samples across the instance.
max_traversal_nodes Maximum containers, leaves, and tensors visited in one input or output walk.
max_container_depth Maximum container edges followed from an input or output root.

1.1.2 ConfigFieldSpec

vin.diagnostics.model_inspection.ConfigFieldSpec(
    path,
    declared_type,
    configured_type,
    value,
)

One field observed in a construction-free configuration walk.

1.1.2.1 Attributes

Name Description
path Field-name path from the root; sequence positions are decimal strings.
declared_type Human-readable annotation declared by the field’s Pydantic model.
configured_type Fully qualified runtime type of the currently configured value.
value Scalar or enum value; other values use a qualified type marker.

1.1.3 ModelCapture

vin.diagnostics.model_inspection.ModelCapture(
    model,
    *,
    module_paths=None,
    limits=None,
)

Capture bounded tensors from registered module instances.

Enter the context, run the model through its ordinary caller-owned forward, and inspect :attr:snapshots after exit. Hooks never alter module outputs and are removed on both successful and exceptional exits. Inputs are sampled by an instance pre-hook before forward can mutate them. At context entry, the sampling hook follows existing instance pre-hooks and observes their transformations. Hooks added while capture is active may use PyTorch’s prepend ordering and run on either side. Shared limits may truncate either side of an invocation, so snapshots are a bounded trace rather than guaranteed input/output pairs. An exceptional forward has no output sample; leaving the context still removes every hook, and :meth:close provides the same idempotent cleanup for manual use.

max_tensors and max_bytes bound retained output records and copied numeric payload across the capture instance. max_samples_per_tensor bounds each value tuple. max_traversal_nodes and max_container_depth bound each structured input or output walk. They do not impose a total-memory limit; the source model and tensors remain owned by the caller and metadata/record overhead is additional.

1.1.3.1 Parameters

Name Type Description Default
model nn.Module Constructed model that owns the registered modules to observe. required
module_paths Sequence[str] | None Exact registered paths to capture, or None for all paths in named_modules order, including "<root>". None
limits CaptureLimits | None Positive quotas, or None for CaptureLimits defaults. None

1.1.3.2 Attributes

Name Description
snapshots Return a tuple of detached snapshots captured so far.
sampled_bytes Return cumulative source-dtype bytes represented by sampled values.
active Report whether instance hooks are currently registered.

1.1.3.3 Methods

Name Description
close Remove this capture’s hooks and pending calls; repeated calls are safe.
1.1.3.3.1 close
vin.diagnostics.model_inspection.ModelCapture.close()

Remove this capture’s hooks and pending calls; repeated calls are safe.

1.1.4 ModelMetadata

vin.diagnostics.model_inspection.ModelMetadata(
    model_type,
    total_parameters,
    trainable_parameters,
    modules,
)

Registered-module metadata for an already constructed model.

1.1.4.1 Attributes

Name Description
model_type Fully qualified runtime type of the inspected model.
total_parameters Elements in all initialized parameters reachable from the model.
trainable_parameters Elements in all initialized, gradient-enabled reachable parameters.
modules Unique registered modules in traversal order, including the root.

1.1.5 ModelStructureSpec

vin.diagnostics.model_inspection.ModelStructureSpec(
    config_type,
    target_type,
    fields,
)

Construction-free description of one model configuration tree.

Repeated inspection of an unchanged configuration returns equal frozen records. Each call creates a new record and never calls setup_target.

1.1.5.1 Attributes

Name Description
config_type Fully qualified type of the inspected root Pydantic model.
target_type Fully qualified root target_type, or None when absent.
fields Depth-first field records in declaration and sequence-index order.

1.1.6 ModuleMetadata

vin.diagnostics.model_inspection.ModuleMetadata(
    path,
    module_type,
    direct_parameters,
    trainable_parameters,
    direct_buffers,
    training,
)

Static metadata for one registered module in a constructed model.

1.1.6.1 Attributes

Name Description
path Registration path from the model root, represented as "<root>" at the root.
module_type Fully qualified runtime type of the registered module instance.
direct_parameters Elements in initialized parameters registered directly on this module.
trainable_parameters Elements in initialized, gradient-enabled parameters directly on this module.
direct_buffers Elements in initialized buffers registered directly on this module.
training The module’s training flag at inspection time.

1.1.7 TensorSnapshot

vin.diagnostics.model_inspection.TensorSnapshot(
    module_path,
    call_index,
    direction,
    tensor_path,
    shape,
    dtype,
    device,
    numel,
    sampled_bytes,
    values,
    sample_omission_reason=None,
)

Complete source metadata plus a detached, bounded tensor value sample.

Empty tensors retain their shape with an empty value sample and zero bytes. Complex, meta-device, non-strided-layout and quantized tensors are metadata-only: their values are not indexed, copied, densified or cast. sample_omission_reason distinguishes these from empty source tensors. Records remain compatible with standard dataclass serialization.

Metadata describes the full tensor at hook time. Only values is truncated: it is a row-major prefix copied to CPU and converted to immutable Python scalars, so the snapshot neither aliases source storage nor retains its autograd graph.

1.1.7.1 Attributes

Name Description
module_path Registered module path, using "<root>" for the model root.
call_index Zero-based invocation index for module_path in this capture instance.
direction Hook side observed; input and output from one call share an index.
tensor_path Container path from args/kwargs or the output root.
shape Complete source-tensor shape at observation time.
dtype String form of the source-tensor dtype at observation time.
device String form of the source device before the bounded CPU copy.
numel Total number of elements in the full source tensor.
sampled_bytes Source-dtype bytes represented by values in this snapshot.
values Detached CPU scalar prefix bounded by per-tensor and shared quotas.
sample_omission_reason Why numeric sampling is unsupported; None for supported/empty sources.

1.2 Functions

Name Description
capture_model Create an opt-in bounded capture context for one constructed model.
inspect_config Describe a Pydantic configuration tree without constructing its target.
inspect_model Describe registered PyTorch state without running a forward pass.

1.2.1 capture_model

vin.diagnostics.model_inspection.capture_model(
    model,
    *,
    module_paths=None,
    limits=None,
)

Create an opt-in bounded capture context for one constructed model.

Dense strided real, integer and boolean tensors supply bounded scalar samples. Complex, meta, non-strided and quantized tensors supply metadata only, with a reason in TensorSnapshot; no conversion is attempted. All snapshots consume the shared record quota, including metadata-only and empty sources. Once byte or traversal quotas exhaust capture stops.

1.2.1.1 Parameters

Name Type Description Default
model nn.Module Constructed module whose registered instances may be observed. required
module_paths Sequence[str] | None Exact named_modules paths to hook. None selects every registered module, including "<root>". Unknown paths are rejected when the context is entered. None
limits CaptureLimits | None Positive traversal and sample quotas. Defaults to CaptureLimits. None

1.2.1.2 Returns

Name Type Description
ModelCapture Reusable context manager. Each entrance registers instance hooks; exit
ModelCapture removes them even when the caller’s forward raises. Snapshots, byte
ModelCapture accounting, and per-module call indices remain cumulative if the same
ModelCapture context object is entered again.

1.2.2 inspect_config

vin.diagnostics.model_inspection.inspect_config(config)

Describe a Pydantic configuration tree without constructing its target.

The walk records every root field, then descends depth-first into nested Pydantic models and Pydantic models held directly in sequences. Mappings, ordinary dataclasses, and arbitrary structured values are represented by their configured type and are not traversed.

1.2.2.1 Parameters

Name Type Description Default
config BaseModel Root Pydantic configuration. Inspection reads current field values and target_type but never calls setup_target. required

1.2.2.2 Returns

Name Type Description
ModelStructureSpec Frozen structure metadata ordered by Pydantic field declaration and
ModelStructureSpec sequence index. An unchanged configuration produces equal records on
ModelStructureSpec repeated calls.

1.2.3 inspect_model

vin.diagnostics.model_inspection.inspect_model(model)

Describe registered PyTorch state without running a forward pass.

1.2.3.1 Parameters

Name Type Description Default
model nn.Module Already constructed module. Inspection does not change training mode, initialize lazy state, move devices, or execute hooks. required

1.2.3.2 Returns

Name Type Description
ModelMetadata Frozen metadata in named_modules registration order. Model totals
ModelMetadata cover recursively reachable parameters, while each module record counts
ModelMetadata only state registered directly on that module. Uninitialized lazy
ModelMetadata parameters and buffers contribute zero elements; already initialized
ModelMetadata state on the same lazy module is still counted.
Back to top