haiman-protocol 0.1.0__py3-none-any.whl

haiman_protocol/__init__.py

@@ -0,0 +1,99 @@
+"""Haiman protocol — reference SDK (Python).
+
+Open reference implementation of the Haiman personal-AI substrate protocol.
+Schemas (the wire format) are the open artifact; this package is the Python
+binding that loads and validates against them.
+
+Posture: open schema (CC-BY-4.0) + open reference implementation (Apache-2.0)
++ paid conformance authority. See the Haiman platform model.
+
+Public surface:
+
+    from haiman_protocol import (
+        __version__, PROTOCOL_VERSION,
+        validate_payload, validate_envelope, validate_message, validate_handoff_inner,
+        WireEnvelope,
+        ProtocolError, SchemaInvalid, error_response, ERROR_TYPES,
+        OP_TYPES, HANDOFF_TYPES, NOTIFY_EVENT_TYPES,
+        store,
+    )
+"""
+
+from __future__ import annotations
+
+from . import optypes, store
+from .envelope import WireEnvelope
+from .errors import (
+    ERROR_TYPES,
+    IdempotencyConflict,
+    InternalError,
+    NotFound,
+    ProtocolError,
+    RateLimited,
+    SchemaInvalid,
+    ScopeViolation,
+    Unavailable,
+    Uncertified,
+    Ungranted,
+    error_response,
+)
+from .optypes import (
+    AUTONOMY_MODES,
+    CONTEXTS,
+    ENGAGEMENT_STRENGTH,
+    HANDOFF_TYPES,
+    KNOWN_CHANNELS,
+    NOTIFY_EVENT_TYPES,
+    OP_TYPES,
+    POSITIVE_REPLY_SIGNAL_STRENGTH,
+    REJECT_REASONS,
+    RETENTIONS,
+    SIGNAL_TYPES,
+)
+from .validate import (
+    validate_envelope,
+    validate_handoff_inner,
+    validate_message,
+    validate_payload,
+)
+from .version import PROTOCOL_VERSION, __version__
+
+__all__ = [
+    "__version__",
+    "PROTOCOL_VERSION",
+    # validation
+    "validate_payload",
+    "validate_envelope",
+    "validate_message",
+    "validate_handoff_inner",
+    # envelope
+    "WireEnvelope",
+    # errors
+    "ProtocolError",
+    "Uncertified",
+    "Ungranted",
+    "ScopeViolation",
+    "SchemaInvalid",
+    "IdempotencyConflict",
+    "NotFound",
+    "RateLimited",
+    "Unavailable",
+    "InternalError",
+    "error_response",
+    "ERROR_TYPES",
+    # vocabularies
+    "OP_TYPES",
+    "HANDOFF_TYPES",
+    "NOTIFY_EVENT_TYPES",
+    "REJECT_REASONS",
+    "SIGNAL_TYPES",
+    "ENGAGEMENT_STRENGTH",
+    "POSITIVE_REPLY_SIGNAL_STRENGTH",
+    "KNOWN_CHANNELS",
+    "CONTEXTS",
+    "AUTONOMY_MODES",
+    "RETENTIONS",
+    # modules
+    "optypes",
+    "store",
+]

haiman_protocol/envelope.py

@@ -0,0 +1,70 @@
+"""The canonical cross-vendor wire envelope — haiman_protocol_schemas.md 1.3.
+
+This is the W3C-native form services exchange off-platform: ``subject`` is a
+W3C DID, ``service_certification`` and ``grant_credential`` are W3C VCs.
+
+Haiman's own in-process services use a slim envelope (integer user_id, internal
+service ids, no VCs) because they run inside one trust boundary; that slim form
+stays in the monorepo. The SDK ships the canonical wire form, which is what a
+third-party implementer needs.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _new_op_id() -> str:
+    # Production mints UUID v7 for time-ordering; the schema accepts any UUID.
+    return str(uuid.uuid4())
+
+
+@dataclass
+class WireEnvelope:
+    """A protocol message envelope in the cross-vendor wire form."""
+
+    op_type: str
+    subject: str
+    payload: dict
+    op_id: str = field(default_factory=_new_op_id)
+    timestamp: str = field(default_factory=_now_iso)
+    scope_ref: str | None = None
+    service_certification: str | None = None
+    grant_credential: str | None = None
+    status: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise, omitting unset optional fields."""
+        out: dict[str, Any] = {
+            "op_id": self.op_id,
+            "op_type": self.op_type,
+            "timestamp": self.timestamp,
+            "subject": self.subject,
+            "payload": self.payload,
+        }
+        for key in ("scope_ref", "service_certification", "grant_credential", "status"):
+            value = getattr(self, key)
+            if value is not None:
+                out[key] = value
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WireEnvelope":
+        return cls(
+            op_type=data["op_type"],
+            subject=data["subject"],
+            payload=data.get("payload", {}),
+            op_id=data.get("op_id", _new_op_id()),
+            timestamp=data.get("timestamp", _now_iso()),
+            scope_ref=data.get("scope_ref"),
+            service_certification=data.get("service_certification"),
+            grant_credential=data.get("grant_credential"),
+            status=data.get("status"),
+        )

haiman_protocol/errors.py

@@ -0,0 +1,120 @@
+"""Protocol error taxonomy — haiman_protocol_schemas.md section 1.5.
+
+This is the canonical, dependency-free version of the error hierarchy that
+``app/protocol.py`` carries inline today. The monorepo refactor (step 1
+follow-on) replaces its local ``ProtocolError`` with these so the wire-form
+error model has one definition.
+
+Each semantic ``type`` maps one-to-one to an HTTP code and a retry posture.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# type -> (http_code, retryable). Mirrors the section 1.5 table.
+ERROR_TYPES: dict[str, tuple[int, bool]] = {
+    "uncertified": (401, False),
+    "ungranted": (403, False),
+    "scope_violation": (403, False),
+    "schema_invalid": (400, False),
+    "idempotency_conflict": (409, False),
+    "not_found": (404, False),
+    "rate_limited": (429, True),
+    "unavailable": (503, True),
+    "internal_error": (500, True),
+}
+
+
+class ProtocolError(Exception):
+    """Base for protocol-layer errors.
+
+    Carries an ``error_type`` from the section 1.5 taxonomy, the matching
+    ``http_code``, and an optional ``retry_after`` (seconds).
+    """
+
+    error_type: str = "internal_error"
+    http_code: int = 500
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_type: str | None = None,
+        http_code: int | None = None,
+        retry_after: int | None = None,
+    ):
+        super().__init__(message)
+        if error_type is not None:
+            self.error_type = error_type
+        if http_code is not None:
+            self.http_code = http_code
+        elif error_type is not None and error_type in ERROR_TYPES:
+            self.http_code = ERROR_TYPES[error_type][0]
+        self.retry_after = retry_after
+
+    @property
+    def retryable(self) -> bool:
+        return ERROR_TYPES.get(self.error_type, (self.http_code, False))[1]
+
+
+class Uncertified(ProtocolError):
+    error_type = "uncertified"
+    http_code = 401
+
+
+class Ungranted(ProtocolError):
+    error_type = "ungranted"
+    http_code = 403
+
+
+class ScopeViolation(ProtocolError):
+    error_type = "scope_violation"
+    http_code = 403
+
+
+class SchemaInvalid(ProtocolError):
+    error_type = "schema_invalid"
+    http_code = 400
+
+
+class IdempotencyConflict(ProtocolError):
+    error_type = "idempotency_conflict"
+    http_code = 409
+
+
+class NotFound(ProtocolError):
+    error_type = "not_found"
+    http_code = 404
+
+
+class RateLimited(ProtocolError):
+    error_type = "rate_limited"
+    http_code = 429
+
+
+class Unavailable(ProtocolError):
+    error_type = "unavailable"
+    http_code = 503
+
+
+class InternalError(ProtocolError):
+    error_type = "internal_error"
+    http_code = 500
+
+
+def error_response(op_id: str, op_type: str, err: ProtocolError) -> dict[str, Any]:
+    """Build the section 1.5 error envelope for an async/sync failure."""
+    error: dict[str, Any] = {
+        "code": err.http_code,
+        "type": err.error_type,
+        "message": str(err),
+    }
+    if err.retry_after is not None:
+        error["retry_after"] = err.retry_after
+    return {
+        "op_id": op_id,
+        "op_type": op_type,
+        "status": "error",
+        "error": error,
+    }

haiman_protocol/optypes.py

@@ -0,0 +1,93 @@
+"""Vocabularies — convenience constants for the v1 protocol.
+
+These mirror enums encoded in the JSON Schemas and the scope/identity
+vocabularies in haiman_protocol.md / haiman_protocol_schemas.md. The schemas
+are the source of truth; ``tests/test_optypes_match_schemas.py`` asserts the
+constants here cannot drift from the bundled schema files.
+"""
+
+from __future__ import annotations
+
+# The nine v1 operations (haiman_protocol_schemas.md section 2).
+OP_TYPES: frozenset[str] = frozenset(
+    {
+        "handshake.v1",
+        "propose.v1",
+        "edit.v1",
+        "accept.v1",
+        "reject.v1",
+        "contribute-signal.v1",
+        "query.v1",
+        "handoff.v1",
+        "notify.v1",
+    }
+)
+
+# Typed handoffs in the v1 starter registry (section 3.2).
+HANDOFF_TYPES: frozenset[str] = frozenset(
+    {
+        "engagement-flag-to-sdr.v1",
+        "positive-reply-to-crm.v1",
+        "stalled-deal-reactivate.v1",
+    }
+)
+
+# notify.v1 event vocabulary (section 3.3).
+NOTIFY_EVENT_TYPES: frozenset[str] = frozenset(
+    {
+        "scope.revoked",
+        "scope.expiring",
+        "scope.autonomy_changed",
+        "profile.updated",
+        "signal_retention.changed",
+        "adapter.updated",
+        "op.failed",
+        "service.disconnected",
+        "handoff.received",
+        "schema.version_sunset",
+    }
+)
+
+# reject.v1 reason enum (section 2.5).
+REJECT_REASONS: frozenset[str] = frozenset(
+    {
+        "off_voice",
+        "factually_wrong",
+        "wrong_tone",
+        "too_long",
+        "too_short",
+        "wrong_intent",
+        "user_changed_mind",
+        "other",
+    }
+)
+
+# contribute-signal.v1 signal types (section 2.6).
+SIGNAL_TYPES: frozenset[str] = frozenset({"edit_pair", "accept", "reject", "comparative"})
+
+# engagement-flag-to-sdr.v1 strength enum (section 3.2).
+ENGAGEMENT_STRENGTH: frozenset[str] = frozenset({"warm", "hot", "cold"})
+
+# positive-reply-to-crm.v1 signal_strength enum (section 3.2).
+POSITIVE_REPLY_SIGNAL_STRENGTH: frozenset[str] = frozenset({"high", "medium", "low"})
+
+# --- Scope / identity vocabularies (haiman_protocol.md section 2). These are
+# not encoded in the op payload schemas; they govern the grant model. ---
+
+# propose/edit channel set known at v1 (section 3.4). Extensible: receivers
+# ignore unknown channels, so this is a convenience list, not a hard gate.
+KNOWN_CHANNELS: frozenset[str] = frozenset(
+    {"email", "linkedin", "social_post", "internal_message"}
+)
+
+CONTEXTS: frozenset[str] = frozenset(
+    {"work", "personal", "admin", "sensitive", "custom"}
+)
+
+AUTONOMY_MODES: frozenset[str] = frozenset(
+    {"approval-first", "semi-auto", "full-auto"}
+)
+
+RETENTIONS: frozenset[str] = frozenset(
+    {"30d", "90d", "365d", "indefinite", "no-signal"}
+)

haiman_protocol/schemas/common/envelope.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/common/envelope.schema.json",
+  "title": "Haiman protocol common envelope (v1, cross-vendor wire form)",
+  "description": "Fixed envelope wrapping every protocol message. Identity is W3C-native: subject is a W3C DID; service_certification and grant_credential are W3C Verifiable Credentials. See the Haiman protocol specification section 1.3. Async result envelopes drop grant_credential and add a status field; the handshake op is the one op where scope_ref may be omitted. Unknown fields are ignored by receivers (forward-compatible), so additionalProperties stays permissive.",
+  "type": "object",
+  "required": ["op_id", "op_type", "timestamp", "subject", "payload"],
+  "properties": {
+    "op_id": {
+      "type": "string",
+      "description": "Idempotency key. UUID v7 in production; any UUID string accepted at the schema layer. Retries with the same op_id are no-ops at the receiver.",
+      "minLength": 1
+    },
+    "op_type": {
+      "type": "string",
+      "description": "op.vN format, e.g. propose.v1.",
+      "pattern": "^[a-z][a-z-]*\\.v[0-9]+$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Sender's clock, ISO 8601. Receivers should not reject on skew alone."
+    },
+    "service_certification": {
+      "type": "string",
+      "description": "Compact reference (URN) to a W3C VC of type HaimanServiceCertificationCredential issued by Haiman as conformance authority. Required on requests; omitted on async results.",
+      "minLength": 1
+    },
+    "grant_credential": {
+      "type": "string",
+      "description": "User-issued, Haiman-signed W3C VC (JWT-VC compact form) proving this user authorised this service for these scopes. Present on requests; dropped on async result envelopes.",
+      "minLength": 1
+    },
+    "subject": {
+      "type": "string",
+      "description": "The user identifier as a W3C DID. v1 uses did:web; did:haiman reserved.",
+      "pattern": "^did:[a-z0-9]+:.+"
+    },
+    "scope_ref": {
+      "type": "string",
+      "description": "The specific granted scope this op operates within. Optional only for handshake."
+    },
+    "status": {
+      "type": "string",
+      "description": "Present on async result envelopes only.",
+      "enum": ["pending", "complete", "error"]
+    },
+    "payload": {
+      "type": "object",
+      "description": "Op-specific payload; validate against the matching ops/<op_type>.schema.json."
+    }
+  }
+}

haiman_protocol/schemas/common/error.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/common/error.schema.json",
+  "title": "Haiman protocol error envelope (v1)",
+  "description": "Returned in place of a result when an op fails. See the Haiman protocol specification section 1.5. The error.type taxonomy maps one-to-one to an HTTP code and a retry posture.",
+  "type": "object",
+  "required": ["op_id", "op_type", "status", "error"],
+  "properties": {
+    "op_id": { "type": "string", "minLength": 1 },
+    "op_type": { "type": "string", "pattern": "^[a-z][a-z-]*\\.v[0-9]+$" },
+    "status": { "const": "error" },
+    "error": {
+      "type": "object",
+      "required": ["code", "type", "message"],
+      "properties": {
+        "code": {
+          "type": "integer",
+          "description": "HTTP status code for the semantic type."
+        },
+        "type": {
+          "type": "string",
+          "description": "Semantic error type. Drives retry behaviour.",
+          "enum": [
+            "uncertified",
+            "ungranted",
+            "scope_violation",
+            "schema_invalid",
+            "idempotency_conflict",
+            "not_found",
+            "rate_limited",
+            "unavailable",
+            "internal_error"
+          ]
+        },
+        "message": { "type": "string" },
+        "retry_after": {
+          "type": "integer",
+          "description": "Seconds; populated for rate_limited (and may be set for unavailable)."
+        }
+      }
+    }
+  }
+}

haiman_protocol/schemas/common/tone.v1.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/common/tone.v1.schema.json",
+  "title": "tone.v1 value schema",
+  "description": "Common value schema for a tone result (e.g. query.v1 user.preferences.tone.default). See the Haiman protocol specification section 3.5. primary is drawn from a published vocabulary; modifiers are free-form short tags, unknown ones ignored gracefully.",
+  "type": "object",
+  "required": ["primary"],
+  "properties": {
+    "primary": {
+      "type": "string",
+      "description": "Enum from a published vocabulary (warm-direct, formal-precise, casual-friendly, ...). Not hard-enumed here: the vocabulary grows under minor revisions and receivers ignore unknown values."
+    },
+    "modifiers": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

haiman_protocol/schemas/common/topic.v1.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/common/topic.v1.schema.json",
+  "title": "topic.v1 value schema",
+  "description": "Common value schema for an engaged topic (e.g. query.v1 user.context.recent_topics). See the Haiman protocol specification section 3.5.",
+  "type": "object",
+  "required": ["label"],
+  "properties": {
+    "label": { "type": "string" },
+    "weight": { "type": "number", "minimum": 0, "maximum": 1 },
+    "last_engaged_at": { "type": "string", "format": "date-time" }
+  }
+}

haiman_protocol/schemas/handoffs/engagement-flag-to-sdr.v1.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/handoffs/engagement-flag-to-sdr.v1.schema.json",
+  "title": "engagement-flag-to-sdr.v1 inner_payload",
+  "description": "Social engagement -> SDR outreach handoff. See the Haiman protocol specification section 3.2. display_name and email_or_handle are required at the protocol floor even when the upstream can only supply URN values; role and suggested_outreach_angle are optional.",
+  "type": "object",
+  "required": ["engaged_contact", "engagement_type", "engagement_context", "engagement_strength"],
+  "properties": {
+    "engaged_contact": {
+      "type": "object",
+      "required": ["display_name", "email_or_handle", "platform"],
+      "properties": {
+        "display_name": { "type": "string", "minLength": 1 },
+        "role": { "type": "string" },
+        "email_or_handle": { "type": "string", "minLength": 1 },
+        "platform": { "type": "string", "minLength": 1 }
+      }
+    },
+    "engagement_type": { "type": "string", "minLength": 1 },
+    "engagement_context": {
+      "type": "object",
+      "required": ["post_topic", "engagement_text", "engagement_at"],
+      "properties": {
+        "post_topic": { "type": "string", "minLength": 1 },
+        "engagement_text": { "type": "string", "minLength": 1 },
+        "engagement_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "engagement_strength": {
+      "type": "string",
+      "enum": ["warm", "hot", "cold"]
+    },
+    "suggested_outreach_angle": { "type": "string" }
+  }
+}

haiman_protocol/schemas/handoffs/positive-reply-to-crm.v1.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/handoffs/positive-reply-to-crm.v1.schema.json",
+  "title": "positive-reply-to-crm.v1 inner_payload",
+  "description": "SDR positive reply -> CRM account creation handoff. See the Haiman protocol specification section 3.2. lead_contact.company.domain must be present but may be null (free-email senders). role is optional. source_lead_id / source_company_id are first-party row ids that let the receiver land the deal in the right tenant.",
+  "type": "object",
+  "required": ["lead_contact", "conversation_summary", "signal_strength", "suggested_account_name", "suggested_deal_stage", "outreach_thread_ref"],
+  "properties": {
+    "lead_contact": {
+      "type": "object",
+      "required": ["display_name", "email", "company"],
+      "properties": {
+        "display_name": { "type": "string", "minLength": 1 },
+        "role": { "type": "string" },
+        "email": { "type": "string", "minLength": 1 },
+        "company": {
+          "type": "object",
+          "required": ["name", "domain"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "domain": {
+              "type": ["string", "null"],
+              "description": "Present-but-null is acceptable for free-email senders; absent entirely is not."
+            }
+          }
+        }
+      }
+    },
+    "conversation_summary": { "type": "string", "minLength": 1 },
+    "signal_strength": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "suggested_account_name": { "type": "string", "minLength": 1 },
+    "suggested_deal_stage": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Non-empty string; the CRM service owns its own stage vocabulary, so no enum here."
+    },
+    "outreach_thread_ref": { "type": "string", "minLength": 1 },
+    "source_lead_id": {
+      "type": ["integer", "null"],
+      "description": "Originating SDR lead id. Optional authoritative linkage; absent or null when the sender cannot supply it (receiver falls back to email lookup)."
+    },
+    "source_company_id": {
+      "type": ["integer", "null"],
+      "description": "Originating tenant id. Optional; null when the lead carries no company_id."
+    }
+  }
+}

haiman_protocol/schemas/handoffs/stalled-deal-reactivate.v1.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/handoffs/stalled-deal-reactivate.v1.schema.json",
+  "title": "stalled-deal-reactivate.v1 inner_payload",
+  "description": "CRM stalled deal -> SDR re-engagement handoff. See the Haiman protocol specification section 3.2. Floor is stalled_account with a name; the remaining fields are advisory context for the re-engagement angle. Spec-defined; not yet wired in the live intra-Haiman validator.",
+  "type": "object",
+  "required": ["stalled_account"],
+  "properties": {
+    "stalled_account": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "domain": { "type": ["string", "null"] },
+        "primary_contact": {
+          "type": "object",
+          "properties": {
+            "display_name": { "type": "string" },
+            "role": { "type": "string" },
+            "email": { "type": "string" }
+          }
+        },
+        "deal_stage_at_stall": { "type": "string" }
+      }
+    },
+    "last_activity_at": { "type": "string", "format": "date-time" },
+    "weeks_stalled": { "type": "integer", "minimum": 0 },
+    "last_topic": { "type": "string" },
+    "suggested_reactivation_angle": { "type": "string" }
+  }
+}

haiman_protocol/schemas/ops/accept.v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haiman.ai/protocol/schemas/ops/accept.v1.schema.json",
+  "title": "accept.v1 request payload",
+  "description": "Terminal user accept on a proposal; emits accept signal. See the Haiman protocol specification section 2.4. final_content may differ slightly from the proposal (last-second tweaks); AI treats a difference as a tiny implicit edit.",
+  "type": "object",
+  "required": ["proposal_id", "final_content", "user_action_at"],
+  "properties": {
+    "proposal_id": { "type": "string", "minLength": 1 },
+    "final_content": {
+      "type": "object",
+      "description": "Per-channel shape (section 3.4)."
+    },
+    "user_action_at": { "type": "string", "format": "date-time" }
+  }
+}