Metadata-Version: 2.4
Name: keyhole-sdk
Version: 0.1.2
Summary: Python SDK for interacting with Keyhole-compatible runtimes
Author: Keyhole Solution Foundation
License: Apache-2.0
Project-URL: Homepage, https://github.com/Keyhole-Solution/keyhole-developer-kit
Project-URL: Repository, https://github.com/Keyhole-Solution/keyhole-developer-kit
Project-URL: Documentation, https://github.com/Keyhole-Solution/keyhole-developer-kit/tree/main/packages/python/keyhole-sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pydantic

# keyhole-sdk

Python SDK for interacting with [Keyhole](https://github.com/Keyhole-Solution/keyhole-developer-kit)-compatible runtimes.

## Install

```bash
pip install keyhole-sdk
```

## Quickstart

```python
from keyhole_sdk import KeyholeClient

client = KeyholeClient(base_url="http://localhost:8080")

# Health check
print(client.health())

# Runtime identity and capabilities
identity = client.identity()
print(identity)

# Current runtime state
print(client.state())

# Submit a realization request
receipt = client.realize(
    candidate_digest="sha256:abc123",
    payload={},
)
print(receipt)

# Replay the same digest safely
replay = client.realize(
    candidate_digest="sha256:abc123",
    payload={},
)
print(replay)

client.close()
```

> **Note:** By default the test runtime runs in local-only mode — realization
> is not gated through MCP governance. Set `KEYHOLE_MCP_URL` and
> `KEYHOLE_MCP_TOKEN` on the runtime to enable governed mode.

## API

| Method | Description |
|--------|-------------|
| `health()` | `GET /healthz` — runtime liveness |
| `identity()` | `GET /identity` — runtime identity and capabilities |
| `state()` | `GET /state` — current runtime-local state |
| `realize(candidate_digest, payload)` | `POST /realize` — bounded realization request |
| `close()` | Close the underlying HTTP session |

## Models

Pydantic models are available in `keyhole_sdk.models`:

- `RuntimeIdentity`
- `RuntimeState`
- `RealizationRequest`
- `RealizationReceipt`

## Configuration

```python
client = KeyholeClient(
    base_url="http://localhost:8080",
    timeout=10.0,  # default
)
```

You can also pass a custom `requests.Session` for advanced use cases.

## Compatibility

`RuntimeBridgeClient` is available as a backward-compatible alias for `KeyholeClient`.

## License

Apache 2.0 — see [LICENSE](https://github.com/Keyhole-Solution/keyhole-developer-kit/blob/main/LICENSE).
