Metadata-Version: 2.4
Name: haiman-protocol
Version: 0.1.0
Summary: Open reference SDK and JSON Schemas for the Haiman personal-AI substrate protocol.
Project-URL: Homepage, https://haiman.ai
Project-URL: Source, https://github.com/haiman-ai/haiman-protocol
Author-email: Haiman <carl@haiman.ai>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSE-SCHEMAS
Keywords: agent,did,haiman,personal-ai,protocol,verifiable-credentials
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.18
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# haiman-protocol

Open schemas and reference SDK for the **Haiman protocol**: the contract that
lets a person's AI and a service interoperate under scoped, revocable, audited
grants.

Haiman is the personal-AI substrate layer (the user owns the model; services
are clients of it), sitting above MCP (AI consumes tools) and alongside A2A
(agents coordinate). This repository is the **connective tissue**: the
wire-format schemas and a Python binding for them.

## Posture

Open schema, open reference implementation, paid conformance authority:

- **Schemas** (`schemas/`) are the open artifact, licensed **CC-BY-4.0**.
  Anyone can read and implement against them.
- **Reference SDK** (`src/haiman_protocol/`) is licensed **Apache-2.0**.
- The certification mark, conformance test suite, and production grant-token
  issuer infrastructure are operated by Haiman as the neutral conformance
  authority. They are not in this repository.

This is the OpenID Foundation / Bluetooth SIG / Khronos playbook: open the wire
format, charge for the conformance authority. A schema-donation path to a
neutral standards body is committed in the Haiman platform model.

## What's here

```
schemas/
  common/      envelope, error, and shared value schemas (tone.v1, topic.v1)
  ops/         the nine v1 operations (request payloads)
  handoffs/    typed inter-service handoff inner payloads
src/haiman_protocol/
  validate.py  validate payloads / envelopes / whole messages against the schemas
  errors.py    the section 1.5 error taxonomy (9 semantic types)
  optypes.py   vocabularies (op types, handoff types, notify events, enums)
  envelope.py  the canonical cross-vendor wire envelope (DID + VC fields)
  store.py     locates and loads the bundled schema files
```

The nine operations: `handshake`, `propose`, `edit`, `accept`, `reject`,
`contribute-signal`, `query`, `handoff`, `notify`.

## Install

```bash
pip install -e ".[dev]"   # editable, with test deps
pytest
```

Requires Python 3.10+. The only runtime dependency is `jsonschema`.

## Use

```python
from haiman_protocol import (
    WireEnvelope, validate_payload, validate_message, SchemaInvalid,
)

# Validate just a payload by op type
validate_payload("propose.v1", {
    "instruction": "Draft a follow-up email.",
    "structured_context": {"channel": "email"},
})

# Build and validate a whole message (envelope + payload, and for handoffs the
# inner payload too)
env = WireEnvelope(
    op_type="propose.v1",
    subject="did:web:user.haiman.ai:u:0193abcd",
    scope_ref="scp_0193def",
    service_certification="urn:haiman:vc:cert:0193sdr",
    grant_credential="eyJhbGc...",
    payload={"instruction": "Draft a follow-up email.",
             "structured_context": {"channel": "email"}},
).to_dict()
validate_message(env)   # raises SchemaInvalid on a bad message
```

Validation failures raise `haiman_protocol.SchemaInvalid` (an error type in the
section 1.5 taxonomy) with a readable message and a JSON Pointer to the
offending node.

## Versioning

Schemas are named `op.vN`. Within a major version, adding optional fields is
non-breaking and receivers ignore unknown fields. Breaking changes bump the
version; N-1 is supported for 12 months after N ships. The SDK package version
(`haiman_protocol.__version__`) is independent of the protocol schema
generation (`haiman_protocol.PROTOCOL_VERSION`).

## Status

`v1` schemas, alpha. This is the standalone extraction of the protocol from the
Haiman monorepo's in-process implementation; the design of record is the Haiman
protocol specification.
