skainet-lang-core/sk.ainet.lang.tensor.storage

Package-level declarations

Types

Global hook for the active MemoryTracker.

data class AggregateMemoryReport(val tensorCount: Int, val totalLogicalBytes: Long, val totalPhysicalBytes: Long, val fileBackedBytes: Long, val ownedCount: Int, val borrowedCount: Int, val aliasedCount: Int, val fileBackedCount: Int, val copyCount: Long, val copyBytes: Long, val entries: List<TrackedEntry>)

BufferAccessor

interface BufferAccessor : AutoCloseable

Provides byte-level read access to a BufferHandle, regardless of its ownership mode.

BufferHandle

sealed interface BufferHandle

Ownership / residency mode of a tensor's backing memory.

BufferHandleFactory

object BufferHandleFactory

Factory and conversion utilities for creating BufferHandle instances from common Kotlin types and for slicing existing handles.

BufferResolver

interface BufferResolver

Resolves a BufferHandle into a BufferAccessor that can read the underlying bytes. Platform-specific implementations handle file-backed and device-resident buffers; heap-backed handles are resolved generically.

ByteArrayAccessor

class ByteArrayAccessor(data: ByteArray, offset: Int = 0, val sizeInBytes: Long = (data.size - offset).toLong()) : BufferAccessor

BufferAccessor over a plain ByteArray.

CompressedKvAttention

class CompressedKvAttention(cache: KvCacheStore, dequantStrategy: CompressedKvAttention.DequantStrategy = DequantStrategy.FULL_TILE)

Bridge between KvCacheStore and the SDPA execution path.

DefaultBufferResolver

class DefaultBufferResolver(fileBackedResolver: (BufferHandle.FileBacked) -> BufferAccessor? = null) : BufferResolver

Default resolver that handles heap-backed handles directly and delegates file-backed handles to a fileBackedResolver.

DefaultKvCacheStore

class DefaultKvCacheStore(config: KvCacheConfig) : KvCacheStore

Default KV cache implementation using dense FP32 storage.

DeviceKind

enum DeviceKind : Enum<DeviceKind>

KvCache

@Target(allowedTargets = [AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.FIELD])

annotation class KvCache(val preset: String = "none", val keyBits: Int = 4, val valueBits: Int = 4, val useQjl: Boolean = false, val maxSeqLen: Int = 0, val device: DeviceKind = DeviceKind.AUTO)

Configures TurboQuant KV-cache compression for an attention layer.

KvCacheAnnotationResolver

object KvCacheAnnotationResolver

Resolves KvCache annotations to KvCacheStore instances.

KvCacheBypass

@Target(allowedTargets = [AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.FIELD])

annotation class KvCacheBypass

Disables TurboQuant compression for a specific layer.

KvCacheConfig

data class KvCacheConfig(val numLayers: Int, val numHeads: Int, val headDim: Int, val maxSeqLen: Int, val keyEncoding: TensorEncoding = TensorEncoding.Dense(4), val valueEncoding: TensorEncoding = TensorEncoding.Dense(4), val placement: Placement = Placement.CPU_HEAP.copy(residency = Residency.PERSISTENT))

Configuration for asymmetric K/V encoding policies.

KvCacheMemoryReport

data class KvCacheMemoryReport(val numLayers: Int, val numHeads: Int, val headDim: Int, val maxSeqLen: Int, val currentSeqLen: Int, val keyEncoding: TensorEncoding, val valueEncoding: TensorEncoding, val placement: Placement, val keyPhysicalBytes: Long, val valuePhysicalBytes: Long, val keyLogicalBytes: Long, val valueLogicalBytes: Long)

Memory report for a KV cache instance.

KvCacheStore

interface KvCacheStore

Dedicated KV-cache storage abstraction for inference.

LogicalDType

enum LogicalDType : Enum<LogicalDType>

Logical numeric type — what the tensor values mean semantically.

MemoryDomain

enum MemoryDomain : Enum<MemoryDomain>

MemoryPlanner

class MemoryPlanner(availableDevices: Set<DeviceKind> = setOf(DeviceKind.CPU))

Resolves Placement intent into concrete buffer allocation decisions.

MemoryTracker

class MemoryTracker

Tracks memory allocation events and reports aggregate statistics across all live TensorStorage instances.

Ownership

enum Ownership : Enum<Ownership>

PackedBlockStorage

interface PackedBlockStorage

Shared contract for all packed/quantized block tensor storage formats.

Place

@Target(allowedTargets = [AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.FIELD])

annotation class Place(val device: DeviceKind = DeviceKind.AUTO, val memory: MemoryDomain = MemoryDomain.HOST_HEAP, val requirement: Requirement = Requirement.PREFERRED)

Declares placement intent for a tensor parameter or property.

Placement

data class Placement(val device: DeviceKind = DeviceKind.CPU, val domain: MemoryDomain = MemoryDomain.HOST_HEAP, val residency: Residency = Residency.PERSISTENT, val requirement: Requirement = Requirement.PREFERRED, val fallback: DeviceKind = DeviceKind.CPU)

High-level placement descriptor: where a tensor lives and how the runtime should manage it.

PlacementUnavailableException

class PlacementUnavailableException(message: String) : RuntimeException

Requirement

enum Requirement : Enum<Requirement>

Residency

enum Residency : Enum<Residency>

ResolvedPlacement

data class ResolvedPlacement(val actual: Placement, val usedFallback: Boolean)

StorageMemoryReport

data class StorageMemoryReport(val shape: Shape, val logicalType: LogicalDType, val encoding: TensorEncoding, val ownership: Ownership, val placement: Placement, val logicalBytes: Long, val physicalBytes: Long, val isFileBacked: Boolean, val isAlias: Boolean, val isMutable: Boolean)

Diagnostic snapshot of a single tensor's memory characteristics.

StorageSpec

data class StorageSpec(val logicalType: LogicalDType, val encoding: TensorEncoding = TensorEncoding.Dense(logicalType.sizeInBytes), val ownership: Ownership = Ownership.OWNED, val placement: Placement = Placement.CPU_HEAP)

A storage specification that captures both logical type AND physical encoding + placement intent. This enables factory routing that goes beyond dtype-only decisions.

TensorEncoding

sealed interface TensorEncoding

Physical storage encoding — how tensor data is laid out in memory.

TensorStorage

data class TensorStorage(val shape: Shape, val logicalType: LogicalDType, val encoding: TensorEncoding, val buffer: BufferHandle, val placement: Placement = Placement.CPU_HEAP, val byteOffset: Long = 0, val strides: LongArray? = null, val isContiguous: Boolean = true)

Runtime descriptor for a tensor's backing memory.

TensorStorageFactory

object TensorStorageFactory

Factory methods for constructing TensorStorage from existing SKaiNET types and from raw data. These bridge the old TensorData world to the new storage model.

TrackedEntry

data class TrackedEntry(val name: String, val report: StorageMemoryReport)

TurboQuantKvCacheStore

class TurboQuantKvCacheStore(config: KvCacheConfig, keyConfig: TurboQuantConfig, valueConfig: TurboQuantConfig) : KvCacheStore

KV cache store with TurboQuant compression.

Weights

@Target(allowedTargets = [AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.FIELD])

annotation class Weights(val memory: MemoryDomain = MemoryDomain.MMAP_FILE)

Marks a tensor as an immutable weight that should be file-backed (memory-mapped) when possible.