haiman-protocol 0.1.0

Open reference SDK and JSON Schemas for the Haiman personal-AI substrate protocol.

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

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

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

Use

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.