Metadata-Version: 2.4
Name: heepx
Version: 0.3.0
Summary: Independent, unofficial Python client for HeepX capabilities: discover, download, verify, and load.
Project-URL: Homepage, https://heepx.org
Project-URL: Repository, https://github.com/HeepX/heepx-sdk
Project-URL: Issues, https://github.com/HeepX/heepx-sdk/issues
Project-URL: Changelog, https://github.com/HeepX/heepx-sdk/blob/main/CHANGELOG.md
Author-email: HeepX <maintainers@heepx.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,capability,heepx,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# heepx

[![CI](https://github.com/HeepX/heepx-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/HeepX/heepx-sdk/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/heepx.svg)](https://pypi.org/project/heepx/)
[![Python versions](https://img.shields.io/pypi/pyversions/heepx.svg)](https://pypi.org/project/heepx/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An **independent, unofficial** Python client for loading
[HeepX](https://github.com/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`](https://github.com/HeepX/workspace) and
[`HeepX/standard`](https://github.com/HeepX/standard).

```sh
pip install heepx
```

```python
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`](https://github.com/HeepX/workspace/blob/main/decisions/0005-consumers-pin-tags.md)
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:

```python
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`

```python
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:

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

### `search` and `info`

```python
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:

```python
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.

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

### `update`

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

## Errors

Every exception the client raises is a `heepx.HeepXError`:

```python
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):

```python
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`](https://github.com/HeepX/workspace) for
that.

## Development

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

## License

MIT — see [`LICENSE`](LICENSE).
