OctxPackage

OctxPackage is the read-only Package view returned by open_octx(). It hides the difference between a ZIP archive and an unpacked directory, providing one reading interface for the manifest, Markdown, structured JSONL, and Arrow vectors.

Basic properties

Property	Type	Purpose
`source`	`Path`	Absolute path to the Package file or working directory.
`source_kind`	`str`	`"zip"` or `"directory"`.
`manifest`	`dict`	Independent copy of the manifest; modifying it does not change the Package.
`files`	`tuple[str, ...]`	Payload paths declared in `manifest.files`.
`available_paths`	`frozenset[str]`	Every safe path that actually exists in the container, including unlisted ordinary files.

Reading raw payloads

with open_octx("asset.octx") as package:
    raw = package.read_payload("knowledge/guide.md")

    with package.open_payload("knowledge/guide.md") as stream:
        first_bytes = stream.read(128)

read_payload() and open_payload() can read only payloads declared in manifest.files. Even if an unlisted ordinary file appears in available_paths, these methods cannot read it.

Reading Markdown documents

with open_octx("asset.octx") as package:
    for document in package.iter_documents():
        print(document.path)
        print(document.metadata)
        print(document.body)

Each Document includes its path, read-only frontmatter, Markdown body with frontmatter removed, and original bytes.

Reading structured data

Standard SAG data uses record-by-record iterators so large JSONL files do not need to be loaded into memory at once:

chunks = package.iter_chunks()
events = package.iter_events()
entities = package.iter_entities()
chunk_events = package.iter_chunk_events()
event_entities = package.iter_event_entities()

Other declared JSONL files can be read through iter_jsonl(path). Before calling it, confirm that the corresponding Capability is declared and that validate_octx() has succeeded.

Reading vectors

Vector methods require octx[vectors]:

table = package.read_vector_table("chunks")

for batch in package.iter_vector_batches("events"):
    consume(batch)

target must be "chunks", "events", or "entities". Prefer iter_vector_batches() for large datasets; it reads one RecordBatch at a time while continuously enforcing row-count, value-count, and decoded-byte limits.

Security checks during reads

After the Package is opened, the identity of its source file or directory is retained. Every read confirms that the source has not been replaced or modified. ZIP CRC failures, corrupt DEFLATE data, and reads that exceed limits are converted into stable OCTX errors.

OctxPackage is not a database connection to be shared across threads, and it does not cache application objects. Exit the with block or call close() after reading is complete.