cortext.py

Turnkey pure-Python (ctypes) bindings for Cortext.

The augmem.cortext PyPI package contains all six thin platform natives and downloads the pinned AIST model on first engine creation. Full offline wheels with embedded model chunks remain available on GitHub Releases.

Install from PyPI

pip install augmem.cortext==1.3.0
# or
uv pip install augmem.cortext==1.3.0

The first Cortext instance downloads and verifies the AIST model and tokenizer. Set CORTEXT_AIST_MODEL_PATH to an existing GGUF for offline use.

Install (GitHub Releases wheelhouse)

# Replace version as needed
export CORTEXT_VERSION=1.3.0
export CORTEXT_INDEX="https://github.com/augmem/cortext.py/releases/download/v${CORTEXT_VERSION}/index.html"

pip install "augmem.cortext==${CORTEXT_VERSION}" --find-links "${CORTEXT_INDEX}"
# or
uv pip install "augmem.cortext==${CORTEXT_VERSION}" --find-links "${CORTEXT_INDEX}"

# one-liner
curl -fsSL "https://github.com/augmem/cortext.py/releases/download/v${CORTEXT_VERSION}/install.sh" \
  | bash -s -- "v${CORTEXT_VERSION}"

Pip/uv selects the matching py3-none-<platform> wheel automatically.

Private / mirror simple index (optional)

GitHub Releases are flat files, so a live …/simple/augmem-cortext/ URL is not available on the release itself. Each release includes simple-index.tar.gz (PEP 503 layout with absolute wheel URLs) for hosting on Pages, S3, or an internal index:

tar -xzf simple-index.tar.gz
# serve the extracted simple/ directory, then:
pip install augmem.cortext==1.3.0 --index-url https://your-mirror.example/simple/

Local wheelhouse / editable checkout

# After scripts/build_wheels.py
pip install augmem.cortext==1.3.0 --find-links dist/wheels --no-index

# Dev monorepo (all six natives in-tree)
uv sync
pip install -e .

import cortext

print(cortext.version())

with cortext.Cortext(":memory:") as memory:
    ctx = memory.process_text("Bailey likes tennis balls.", "chat/main")
    emb = memory.embed_text("embed without storing")
    print(len(emb))

For binary attachments, pass Media(data, mimetype) or raw bytes with media_mimetype to process_text_with_media.

Python 3.10+. Binding 1.3.0 tracks engine v1.3.0.

Distribution channels

Default PyPI limits are ~100 MB per file. The PyPI wheel stays below that limit by shipping thin natives and fetching the verified model on first use. GitHub Release wheels are larger but work offline after download.

Local full tree after clone:

python3 scripts/vendor_release_assets.py --from-release v1.3.0 --force
uv sync && uv run pytest -q

What each wheel ships

cortext/
  native/<this-platform-only>/libcortext.* | cortext.dll
  models/   # AIST chunks + vocab + manifest (GitHub Release wheel only)
  *.py      # ctypes binding

Resolution at runtime

No sibling checkouts are searched. The PyPI wheel downloads only its pinned model assets when no explicit model path is provided.

Environment (optional)

Maintainer release flow

# 1) Vendor engine assets (or rely on CI to fetch augmem/cortext release)
python3 scripts/vendor_release_assets.py --from-release v1.3.0 --force

# 2) Build platform wheels + local indexes
python3 scripts/build_wheels.py

# 3) Build the PyPI package from thin natives
python3 scripts/build_pypi.py --native-root /path/to/cortext-thin-v1.3-build

# 4) Tag + push — CI (.github/workflows/release-wheels.yml) builds, writes
#    absolute-URL indexes, and uploads everything to the GitHub Release
git tag v1.3.0
git push origin v1.3.0

# 5) Upload dist/pypi/* to PyPI with a configured API token

Manual publish of an existing wheelhouse:

BASE="https://github.com/augmem/cortext.py/releases/download/v1.3.0"
python3 scripts/write_wheel_index.py dist/wheels --version 1.3.0 --base-url "$BASE"
gh release create v1.3.0 dist/wheels/*.whl dist/wheels/index.html \
  dist/wheels/install.sh dist/wheels/INSTALL.md \
  --title "cortext.py 1.3.0" --notes-file dist/wheels/INSTALL.md

API

• Config, Media, Retention, Cortext, CortextError
• version(), last_error(), load_library(), package_assets_ready()
• process_* / embed_* / consolidate / flush / reset
• materialize_model, resolve_aist_model

Develop / test

uv sync
uv run pytest -q