Appendix

file format 6
Rust SDK 1.0 preview

Reading a pack's appendix: its sections, its named tensors, and the embedding rows bound to entities. An Appendix borrows the pack's buffer and copies nothing.

On this page, Result<T> is std::result::Result<T, plxi_sdk::Error>.

Every public struct and enum with a public field or variant is marked #[non_exhaustive]: code outside the crate builds one through its constructors and matches an enum with a _ arm.

Structs

struct

Appendix

Spec §7

pub struct Appendix<'p> { /* private fields */ }

impl Debug for Appendix

Summary: The embedded CSDT container, opened over the pack's buffer with no copy and no file.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::sections

Spec §7

pub fn sections(&self) -> Vec<SectionInfo>

Summary: The section table.
Parameters: None.
Returns: Vec<SectionInfo>
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::section_bytes

Spec §7

pub fn section_bytes(&self, index: usize) -> Result<Option<&[u8]>>

Summary: The data of section index, CRC-checked on first access (spec §9 step 9). None when index is at or past the section count.
Parameters: index: usize
Returns: Result<Option<&[u8]>>
Errors: appendix_crc_mismatch
unsupported
appendix_crc_mismatch when the section's CRC32C fails; unsupported for a payload class this build does not know.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::tensor_f32

Spec §7

pub fn tensor_f32(&self, name: &str) -> Result<Option<Vec<f32>>>

Summary: Tensor name, dequantized to f32. None when the container has no tensor of that name.
Parameters: name: &str
Returns: Result<Option<Vec<f32>>>
Errors: unsupported
unsupported for a dtype with no f32 route; appendix kinds for a damaged tensor.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::tensor_names

Spec §7

pub fn tensor_names(&self) -> Vec<String>

Summary: Names of the cataloged tensors, sorted.
Parameters: None.
Returns: Vec<String>
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::container_version

Spec §7

pub fn container_version(&self) -> u8

Summary: The container's version byte.
Parameters: None.
Returns: u8
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

Appendix::file_checksum

Spec §7

pub fn file_checksum(&self) -> u32

Summary: The container's section-table CRC32C (file_checksum).
Parameters: None.
Returns: u32
Example: Example 4: Appendix and embeddings
Spec: Spec §7

struct

SectionInfo

Spec §7

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SectionInfo {
    pub index: usize,
    pub section_type: u16,
    pub format_version: u8,
    pub payload_class: u8,
    pub record_count: u64,
    pub record_stride: u32,
    pub dtype: [u8; 8],
    pub checksum: u32,
}

Summary: One section descriptor, as the facade reports it.
Fields: index: usizeSection index in the container's section table.
section_type: u16Section type code, e.g. Compact (0x0020, spec §9 step 10).
format_version: u8Section format version.
payload_class: u8The section's payload class.
record_count: u64Logical records in the section.
record_stride: u32Bytes per record; 0 for sections without fixed-size records.
dtype: [u8; 8]The section's inline dtype bytes.
checksum: u32The descriptor's CRC32C of the section data.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

method

SectionInfo::to_json_value

Spec §7

pub fn to_json_value(&self) -> Value

Summary: {index, type, record_count, record_stride,...} with snake_case keys.
Parameters: None.
Returns: Value
Example: Example 4: Appendix and embeddings
Spec: Spec §7

struct

BoundEmbedding

Spec §9

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BoundEmbedding {
    pub entity_id: String,
    pub row: Vec<u8>,
}

Summary: One bound embedding: the entity and its record bytes.
Fields: entity_id: StringThe embref's entity_id.
row: Vec<u8>The bound record's bytes (COMPACT_RECORD_SIZE under BindProfile::Compact).
Example: Example 4: Appendix and embeddings
Spec: Spec §9

Enums

enum

BindProfile

Spec §9

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BindProfile {
    Compact,
}

Summary: How an embref target is bound (spec §9 step 10). The profile belongs to the consumer, not to the file format.
Variants: CompactCompact embedding profile: a Compact section, record stride COMPACT_RECORD_SIZE, dtype RECORD.
Example: Example 4: Appendix and embeddings
Spec: Spec §9

Constants

const

COMPACT_RECORD_SIZE

Spec §7

pub const COMPACT_RECORD_SIZE: usize = 320;

Summary: Bytes per Compact embedding row: 320.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

const

COMPACT_FORMAT_VERSION

Spec §7

pub const COMPACT_FORMAT_VERSION: u8 = 2;

Summary: The format version the SDK writes in a Compact section's descriptor.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

const

COMPACT_ALIGN_LOG2

Spec §7

pub const COMPACT_ALIGN_LOG2: u8 = 6;

Summary: The alignment of Compact rows, as a power of two: 6, so 64 bytes.
Example: Example 4: Appendix and embeddings
Spec: Spec §7

Anyone may implement this format. Copying or republishing the text of this specification requires permission from Cintile Inc.