create_octx()

Create an OCTX Package from Markdown and optional structured data while managing stable identity.

create_octx() creates an immutable .octx Package. It maintains Asset, Document, and Release identities; generates the manifest and digests; writes a temporary archive; performs full validation; and only then publishes it to output.

Signature

def create_octx(
    workspace: os.PathLike[str] | str,
    *,
    output: os.PathLike[str] | str,
    source: os.PathLike[str] | str | None = None,
    name: str | None = None,
    version: str | None = None,
    derive: bool = False,
    capabilities: Mapping[str, str | Mapping[str, Any]] | None = None,
    limits: ArchiveLimits | None = None,
) -> CreateResult

Parameters

Parameter	Purpose
`workspace`	Reusable production directory that stores `knowledge/`, `manifest.json`, and local `.octx/state.json`.
`output`	The `.octx` file to publish. Existing content that differs is not overwritten.
`source`	Markdown directory copied into the workspace; the source directory is not modified.
`name`	Required when creating an Asset for the first time; subsequent calls reuse the saved name by default.
`version`	SemVer for the Release. The first Release defaults to `1.0.0`; the version must increase after content changes.
`derive`	Create a new Asset from an unpacked external Package and record `asset.derived_from`.
`capabilities`	Explicitly declare capabilities, for example `{"sag-structured": "0.1"}`; they are not inferred from files.
`limits`	`ArchiveLimits` used during creation and validation.

source always uses copy semantics. create_octx() never moves, renames, or rewrites files in the source directory.

First creation

from octx import create_octx

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

print(result.asset_id)
print(result.version)          # 1.0.0
print(result.package_digest)

After the first successful creation, local state in the workspace records stable Asset and Document IDs. Do not create a new workspace for every version of the same Asset.

Publishing a subsequent Release

After modifying workspace content, increase the version and specify a new output file:

result = create_octx(
    "./.octx-workspace",
    version="1.1.0",
    output="./product-guide-1.1.0.octx",
)

The same logical content can be rebuilt reproducibly under the same version. Publication is rejected if the same Asset and version produce a different Package Digest. A version rollback, or changed content without a version increase, raises ReleaseVersionError.

Declaring SAG-Structured

Declaring a Capability does not generate data automatically. sag-structured requires all JSONL and relationship files to already exist in the workspace and to satisfy the complete-coverage constraints.

result = create_octx(
    "./.octx-workspace",
    version="2.0.0",
    output="./product-guide-2.0.0.octx",
    capabilities={
        "sag-structured": "0.1",
        "vectors": "0.1",
    },
)

External Packages and derivation

For an unpacked Package that has no local producer state:

If its content is unchanged, it can be repackaged losslessly while preserving the original Asset ID, version, Package Digest, and unknown fields.
If its content has changed, pass derive=True to create a new Asset. It must not impersonate a subsequent Release from the original publisher.

derived = create_octx(
    "./external-expanded",
    derive=True,
    output="./derived.octx",
)

The derived result uses a new asset_id; its first Release starts at 1.0.0 by default and records the source Asset ID, version, and Package Digest.

Return value

Returns CreateResult, which includes the output path, workspace, Asset ID, Release version, creation time, Package Digest, Document ID mapping, and complete ValidationReport.

If creation fails, no partial Package is published to output. Common exceptions include ReleaseVersionError, DerivationRequired, OutputExistsError, and OctxValidationError.