Open Context Python API

Install octx and learn its public entry points, call sequence, and minimal usage.

octx is the independent Python reference implementation of Open Context. It creates, opens, validates, and safely unpacks .octx Packages without depending on SAG, a database, or a retrieval backend.

Installation

Python 3.11 or later is required:

python -m pip install octx

Install the vectors extra to read or validate Arrow vector files:

python -m pip install "octx[vectors]"

Public entry points

API	Purpose
`create_octx()`	Create an immutable `.octx` Package from Markdown or an existing workspace, or publish a subsequent Release.
`open_octx()`	Safely open a ZIP file or unpacked directory and obtain a read-only `OctxPackage`.
`validate_octx()`	Fully validate the OCTX format and known Capabilities, returning a structured report.
`unpack_octx()`	After validation succeeds, safely unpack the manifest and declared payloads into a directory.
`OctxPackage`	Read the manifest, Markdown, JSONL structure layer, and Arrow vectors.
`CreateResult`	Path, identity, version, digest, and validation result after `create_octx()` succeeds.
`Document`	Read-only view of a Markdown document in a Package.
`ValidationReport`	Structured validation report for the OCTX format and Capabilities.
`ArchiveLimits`	Resource-safety limits used during creation, opening, validation, and unpacking.
CLI	The `octx create / inspect / validate / unpack` commands.
Error handling	Public exceptions, error codes, and recommended handling.

Minimal workflow

Assume knowledge/ contains at least one Markdown document:

from octx import create_octx, open_octx, validate_octx

result = create_octx(
    "./.octx-workspace",
    source="./knowledge",
    name="Product Guide",
    output="./product-guide.octx",
)

report = validate_octx(result.output)
assert report.valid
assert report.fully_validated

with open_octx(result.output) as package:
    for document in package.iter_documents():
        print(document.path, document.metadata["title"])

source is not modified. workspace preserves stable Asset, Document, and Release identities; continue using the same workspace when publishing subsequent Releases of the same Asset.

Call order

For a Package you just created, you can use CreateResult.report directly. For an external or untrusted Package, the recommended order is:

Use validate_octx() to obtain a structured report without interrupting the workflow for ordinary format errors.
Check both report.valid and report.fully_validated.
After validation satisfies your acceptance policy, use open_octx() to read the Package or unpack_octx() to unpack it.

A successful open_octx() call means only that the container can be opened safely. It does not mean that all content has passed OCTX specification validation.