heepx 0.3.0

Independent, unofficial Python client for HeepX capabilities: discover, download, verify, and load.

heepx

An independent, unofficial Python client for loading HeepX capability repositories. Not affiliated with or governed by the HeepX organization's HXS-1 standard, and not itself a capability or infrastructure repository under that standard — for the actual capability ecosystem, its charter, and its governance, start at HeepX/workspace and HeepX/standard.

pip install heepx

import heepx

warrant = heepx.learn("warrant")
print(warrant.name, warrant.version)

What this is

A HeepX capability is a specification plus a deterministic evaluation suite, published as a git repository, pinned by consumers at a release tag (never a branch — see decisions/0005 in workspace). This client is how a Python program finds one, downloads it, checks that what it downloaded is intact, and loads it as a typed value — nothing more. It does not execute a capability, and it does not talk to any model provider; that is a different concern, layered on top of the Capability object this client hands back.

Whether loading a capability measurably helps is not yet established. The ecosystem's own honest status (workspace/CHARTER.md): one controlled benchmark, one small model, a placebo-controlled delta of +0.208 at p=0.125 (not significant), against a prompt-length cost significant at p=0.008. Read plainly: loading a capability document measurably costs something, and whether it measurably helps is unproven. This client makes that easier to test, not something already settled.

The public API

Six functions, and this is the whole surface:

import heepx

heepx.search("claim")  # -> list of matching capabilities
heepx.info("warrant")  # -> registry metadata, no download
warrant = heepx.learn("warrant")  # -> download (if needed) and load
heepx.list()  # -> names of capabilities installed locally
heepx.verify("warrant")  # -> integrity check against the local cache
heepx.update("warrant")  # -> fetch the newest version

learn

warrant = heepx.learn("warrant")
print(warrant.name)  # "warrant"
print(warrant.version)  # "1.2.1"
print(warrant.fingerprint)  # content hash of every file
print(warrant.dependencies)  # other capabilities this one composes with

A version already in the local cache is never re-downloaded. Pin an exact version, or work offline once something is cached:

heepx.learn("warrant", version="v1.1.0")  # exactly as info() reports it
heepx.learn("warrant", offline=True)  # never touches the network

search and info

for result in heepx.search("plan"):
    print(result.name, "-", result.description)

meta = heepx.info("warrant")
print(meta.latest_version, meta.versions)

list

Capabilities already downloaded, not the full registry:

heepx.list()  # ["warrant", "planning"]

verify

Recomputes the fingerprint of a cached capability's files and compares it to what was recorded when it was downloaded — the check that catches local corruption or tampering that a one-time download checksum cannot.

result = heepx.verify("warrant")
if not result.ok:
    print(result.reasons)

update

heepx.update("warrant")  # fetch and load the newest version

Errors

Every exception the client raises is a heepx.HeepXError:

try:
    heepx.learn("does-not-exist")
except heepx.CapabilityNotFoundError:
    ...
except heepx.OfflineError:
    ...
except heepx.HeepXError:
    ...  # catch-all

Beyond the six functions

The registry and cache are pluggable, for anyone who needs a private or offline mirror, or an isolated cache directory (tests, CI):

from heepx.registry import LocalRegistry
from heepx.cache import Cache

reg = LocalRegistry(index_path=Path("index.json"), archive_dir=Path("archives"))
cache = Cache(root=Path("/tmp/my-cache"))
heepx.learn("warrant", registry=reg, cache=cache)

Registry is an abstract base class — a future registry provider implements its four methods and every caller above keeps working unchanged.

Not in scope

This client does capability discovery, download, verification, and loading. It does not execute capabilities, and it does not integrate with any model provider (Anthropic, OpenAI, Ollama, or otherwise). Those are separate concerns for a layer above this one. It also does not speak for the HeepX organization — see workspace for that.

Development

pip install -e ".[dev]"
pre-commit install
ruff check .
mypy src
pytest

License

MIT — see LICENSE.