lcp-sdk 1.0.0__tar.gz

lcp_sdk-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+# macOS
+.DS_Store
+
+# Local tooling artifacts — never published
+.gitnexus/
+.claude/
+graphify-out/
+CLAUDE.md
+.hermes.md
+*.pyc
+__pycache__/
+
+# Local platform/runtime state
+.venv/
+data/
+*.sqlite3

lcp_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: lcp-sdk
+Version: 1.0.0
+Summary: LCP (Lead Context Protocol) SDK for validation, signing, and HTTP integrations.
+Project-URL: Documentation, https://github.com/SpearSystems/LCP
+Project-URL: Source, https://github.com/SpearSystems/LCP
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: referencing>=0.35.0

lcp_sdk-1.0.0/README.md

@@ -0,0 +1,149 @@
+# LCP Python SDK
+
+Tier 1 maintained reference SDK for LCP publishers, buyers, platforms, and
+webhook receivers. It is independent of MCP and does not contain platform
+routing or storage logic.
+
+## Install
+
+From the repository while the package is unreleased:
+
+```bash
+python3 -m pip install -e implementations/sdk/python
+```
+
+When a release is published:
+
+```bash
+python3 -m pip install lcp-sdk
+```
+
+The package targets Python 3.10+ and bundles the canonical schemas in released
+wheels. See the [SDK support policy](../../../docs/SDK-ROADMAP.md) for
+compatibility and release gates.
+
+## Build and validate messages
+
+```python
+from lcp_sdk import SchemaValidator, build_envelope
+
+lead = build_envelope(
+    "lead",
+    sender_id="publisher_001",
+    receiver_id="platform_001",
+    payload={
+        "lead_id": "lead_123",
+        "status": "NEW",
+        "channel": "form",
+        "consumer": {"phone": "+61412345678"},
+        "location": {"country_code": "AU", "postal_code": "2000"},
+        "attributes": {"vertical": "mortgage", "schema_version": "1.0.0"},
+    },
+)
+
+SchemaValidator().require_valid_envelope(lead)
+```
+
+`SchemaValidator` validates the envelope, message payload, offer documents,
+and the ping-safe tags in vertical schemas. The released wheel bundles the
+canonical Draft 2020-12 schemas and generated `TypedDict` models in
+`lcp_sdk.generated.models`; set `LCP_SCHEMA_DIR` when using an external schema
+release instead.
+
+## HTTP client
+
+```python
+from lcp_sdk import LCPClient, SchemaValidator
+
+client = LCPClient(
+    "https://platform.example",
+    sender_id="publisher_001",
+    hmac_secret="secret-from-your-secret-manager",
+    validator=SchemaValidator(),
+    max_retries=2,
+)
+ack = client.submit_lead(lead)
+status = client.query_lead_status("lead_123")
+offers = client.list_offers(vertical="mortgage")
+capabilities = client.get_capabilities()
+```
+
+The client provides:
+
+| Method | Operation |
+|---|---|
+| `submit_lead` | Submit a lead envelope |
+| `submit_call` | Submit a call envelope |
+| `submit_bid` | Submit a bid envelope |
+| `query_lead_status` | Query lead lifecycle/status |
+| `get_schema` | Retrieve a core or vertical schema |
+| `get_capabilities` | Discover endpoint capabilities |
+| `list_offers` | Discover active offers |
+| `request` | Make an authenticated LCP HTTP request |
+
+`429`, `500`, `502`, `503`, `504`, and transport errors are retried with
+exponential backoff. Mutating requests must use a stable envelope idempotency
+key when retrying. Non-success responses raise `LCPHTTPError` with the status
+code and parsed error body.
+
+## Authentication and webhook verification
+
+HMAC requests use the approved canonical input:
+
+```text
+<timestamp>\n<idempotency-key>\n<raw-request-body>
+```
+
+The body must be the exact bytes sent on the wire. The SDK sends
+`X-LCP-Timestamp`, `X-LCP-Idempotency-Key`, `X-LCP-Signature`, and
+`X-LCP-Sender-Id`. Bearer authentication is also supported.
+
+For a webhook or framework receiver, verify the raw body before JSON parsing:
+
+```python
+from lcp_sdk import verify_http_request
+
+headers = {
+    "X-LCP-Signature": request.headers["X-LCP-Signature"],
+    "X-LCP-Timestamp": request.headers["X-LCP-Timestamp"],
+    "X-LCP-Idempotency-Key": request.headers["X-LCP-Idempotency-Key"],
+}
+verify_http_request("partner-secret", headers, request.get_data())
+```
+
+`verify_http_request` enforces the signature and replay window. Applications
+must still perform durable idempotency claims, authorization, schema
+validation, and PII-safe logging.
+
+Low-level helpers are also available: `canonical_signing_bytes`, `sign_hmac`,
+and `verify_hmac`.
+
+## Test mode
+
+Pass `test=True` to mutating client methods when sending synthetic traffic.
+The SDK emits `X-LCP-Test: true`; the envelope should also have `test=True`.
+Production receivers should reject mismatched or unexpected test traffic.
+
+## Tests
+
+```bash
+PYTHONPATH=implementations/sdk/python \
+  python3 -m unittest discover -s implementations/sdk/python/tests -v
+```
+
+The SDK tests include the shared cross-language HMAC fixture in
+`test-vectors/sdk/hmac.json`.
+
+## Publishing
+
+The repository includes a GitHub Actions Trusted Publishing workflow for the
+SDK, MCP adapter, and reference platform. Before tagging a release, configure
+one PyPI Trusted Publisher for each package and keep package versions aligned
+with the release process. The workflow publishes on `v*` tags; it does not
+require a long-lived PyPI token in GitHub secrets.
+
+## Scope
+
+The SDK intentionally does not implement buyer offer matching, auctions,
+webhook queues, CRM handoff, or persistence. Those belong to the reference
+platform or the operator's deployment.

lcp_sdk-1.0.0/generated/models.py

@@ -0,0 +1,160 @@
+"""GENERATED FROM schemas/ — do not edit manually.
+
+These TypedDicts are generated from the canonical schema set. Runtime
+acceptance remains the JSON Schema validator's responsibility.
+"""
+from __future__ import annotations
+
+from typing import Any, NotRequired, TypedDict
+
+JsonObject = dict[str, Any]
+
+
+class MessageModel(TypedDict, total=False):
+    id: str
+    type: str
+    timestamp: str
+    sender_id: str
+    receiver_id: str
+    correlation_id: str | None
+    idempotency_key: str
+    test: NotRequired[bool]
+    security: NotRequired[JsonObject]
+
+
+class EnvelopeModel(TypedDict):
+    lcp: dict[str, Any]
+
+
+class LeadPayload(TypedDict, total=False):
+    lead_id: str
+    external_id: NotRequired[str]
+    submitted_at: NotRequired[str]
+    status: str
+    channel: str
+    consumer: JsonObject
+    location: JsonObject
+    compliance: NotRequired[JsonObject]
+    provenance: NotRequired[JsonObject]
+    attributes: JsonObject
+    exclusivity: NotRequired[JsonObject]
+    contact_window: NotRequired[JsonObject]
+    lead_quality: NotRequired[JsonObject]
+    expiry: NotRequired[JsonObject]
+    attachments: NotRequired[list[JsonObject]]
+
+
+class CallPayload(TypedDict, total=False):
+    lead_id: str
+    external_id: NotRequired[str]
+    submitted_at: NotRequired[str]
+    status: str
+    channel: str
+    consumer: JsonObject
+    location: JsonObject
+    call: JsonObject
+    compliance: NotRequired[JsonObject]
+    provenance: NotRequired[JsonObject]
+    attributes: NotRequired[JsonObject]
+    expiry: NotRequired[JsonObject]
+    exclusivity: NotRequired[JsonObject]
+    attachments: NotRequired[list[JsonObject]]
+
+
+class PingPayload(TypedDict, total=False):
+    ping_id: str
+    lead_reference: str
+    publisher_id: NotRequired[str]
+    offer_id: NotRequired[str]
+    phone_hash: str
+    email_hash: NotRequired[str]
+    country_code: str
+    state_region: NotRequired[str]
+    postal_code: NotRequired[str]
+    vertical: str
+    lead_age_minutes: NotRequired[int]
+    attributes: NotRequired[JsonObject]
+    compliance_flags: NotRequired[JsonObject]
+    quality_flags: NotRequired[JsonObject]
+    floor_price_cents: int
+    currency: str
+    exclusivity: NotRequired[str]
+    dedup_window_hours: NotRequired[int]
+    expires_at: NotRequired[str]
+
+
+class PostPayload(TypedDict, total=False):
+    lead_id: str
+    delivered_at: str
+    submitted_at: NotRequired[str]
+    offer_id: NotRequired[str]
+    price_cents: int
+    currency: str
+    buyer_id: str
+    buyer_reference: NotRequired[str]
+    pricing: NotRequired[JsonObject]
+    matched_preferences: NotRequired[JsonObject]
+    consumer: JsonObject
+    location: JsonObject
+    compliance: NotRequired[JsonObject]
+    attributes: JsonObject
+    provenance: NotRequired[JsonObject]
+    exclusivity: NotRequired[JsonObject]
+    call: NotRequired[JsonObject]
+    attachments: NotRequired[list[JsonObject]]
+
+
+class BidPayload(TypedDict, total=False):
+    ping_id: str
+    decision: str
+    bid_price_cents: int
+    currency: str
+    estimated_contact_seconds: NotRequired[int]
+    buyer_reference: NotRequired[str]
+    reject_reason: NotRequired[str]
+    capacity_remaining: NotRequired[int]
+
+
+class AckPayload(TypedDict, total=False):
+    original_message_id: str
+    status: str
+    errors: NotRequired[list[JsonObject]]
+    lead_id: NotRequired[str]
+    request_id: NotRequired[str]
+    rejection_reason: NotRequired[str]
+
+
+class EventPayload(TypedDict, total=False):
+    lead_id: str
+    event: str
+    timestamp: str
+    details: NotRequired[JsonObject]
+    external_reference: NotRequired[str]
+
+
+class OfferModel(TypedDict, total=False):
+    offer_id: str
+    buyer_id: str
+    tenant_id: NotRequired[str]
+    active: NotRequired[bool]
+    routing_mode: NotRequired[str]
+    vertical: str
+    schema_version: NotRequired[str]
+    countries: list[str]
+    state_regions: NotRequired[list[str]]
+    postal_codes: NotRequired[list[str]]
+    channels: NotRequired[list[str]]
+    floor_price_cents: int
+    currency: str
+    extensions: NotRequired[JsonObject]
+    allowed_publisher_ids: NotRequired[list[str]]
+    allowed_brand_ids: NotRequired[list[str]]
+    attribute_equals: NotRequired[JsonObject]
+    attribute_in: NotRequired[JsonObject]
+    monthly_minimum_payable: NotRequired[int]
+    monthly_maximum_payable: NotRequired[int]
+    monthly_quota_timezone: NotRequired[str]
+    monthly_quota_policy: NotRequired[str]
+    payable_rules: NotRequired[JsonObject]
+    call_routing_mode: NotRequired[str]
+    connect_timeout_seconds: NotRequired[int]

lcp_sdk-1.0.0/generated/schema-manifest.json

@@ -0,0 +1,21 @@
+{
+  "protocol_version": "1.0.0",
+  "schema_files": {
+    "schemas/ack.json": "7946d73afff4653c68ef4842986d9e5a4839ab2765346c706b8a60f46c060e4c",
+    "schemas/bid.json": "c7a1c901c562e303ec7cceb9418d5d40d33f47d1360779ea5b8ec80a9e6bce05",
+    "schemas/call.json": "142aa654c964493cd67721921f1614a9f8635807732b816671bf5d0053bf2fe2",
+    "schemas/core.json": "8385f2a7b02aa7c1e5bde67afa4247dfe8c6c1d2e5bdb5783f70546b01445cac",
+    "schemas/envelope.json": "69bde360f9a985662ffef8d0f63dc3acbcf8d773c3fa763b70cc9e75f69a2606",
+    "schemas/event.json": "e3c93ab2aa464a8401392ece2093abe207050bc372086763f373498048fd63fc",
+    "schemas/lead.json": "dd5989503d9d8d2cf65114578d06e6300a767d8f9ae5c14b43bab456bd2bf2e6",
+    "schemas/offer.json": "bfaf6a67d1fc00aff8d79965aad4456130d5960b56e8e011cba9a069ad0cb6e3",
+    "schemas/ping.json": "d4c12a61f534383744636756e0952a4afe092d2c8070602289bedc51356e7d16",
+    "schemas/post.json": "3fc42124c299df5534d0b46be14385e7dfec8771a804946e907c90577bf7bfdb",
+    "verticals/home_services.json": "1f022bef90a8f989157e77ac3cebd5d054285bf45d788147adcf398a4e8967ff",
+    "verticals/insurance.json": "ba9fd38fbad18b2016bffa54722ad71295de5d309397a84122aa7bb906a3f810",
+    "verticals/legal.json": "b4f428230cce6b8a008bca5c01f27069ed9bea37736f3d699194457b2e1f02cf",
+    "verticals/mortgage.json": "3570b113753453055af2d7a027e0a13afab8c2e3a054e347395c1900a99aa03c",
+    "verticals/mva.json": "07138d68241e9f1e96f531d62bfa53bdf0d5b5dc1a6153fa32e88a3616e927d3",
+    "verticals/solar.json": "a2c0079ead33360dd6c0449a4799b31913956cd2b25b69d952d4bf1f708744cb"
+  }
+}

lcp_sdk-1.0.0/lcp_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""Standalone LCP SDK for Python integrations."""
+
+from .client import LCPClient, LCPHTTPError
+from .envelope import build_envelope, message_metadata, utc_timestamp
+from .signing import SignatureError, canonical_signing_bytes, sign_hmac, verify_hmac
+from .validation import SchemaValidator, ValidationError
+from .webhook import verify_http_request
+
+__all__ = [
+    "LCPClient",
+    "LCPHTTPError",
+    "SchemaValidator",
+    "SignatureError",
+    "ValidationError",
+    "build_envelope",
+    "canonical_signing_bytes",
+    "message_metadata",
+    "sign_hmac",
+    "utc_timestamp",
+    "verify_hmac",
+    "verify_http_request",
+]
+
+__version__ = "1.0.0"

lcp_sdk-1.0.0/lcp_sdk/client.py

@@ -0,0 +1,163 @@
+"""HTTP client for LCP-compatible endpoints."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .envelope import message_metadata, utc_timestamp
+from .signing import sign_hmac
+from .validation import SchemaValidator
+
+
+class LCPHTTPError(RuntimeError):
+    """Raised when an LCP endpoint returns a non-success response."""
+
+    def __init__(self, status_code: int, body: Any):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"LCP HTTP {status_code}: {body}")
+
+
+class LCPClient:
+    """Small, dependency-light client for the LCP HTTP binding."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        sender_id: str | None = None,
+        api_key: str | None = None,
+        hmac_secret: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        validator: SchemaValidator | None = None,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.sender_id = sender_id
+        self.api_key = api_key
+        self.hmac_secret = hmac_secret
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.validator = validator
+
+    def _headers(
+        self,
+        body: bytes,
+        *,
+        idempotency_key: str | None,
+        test: bool = False,
+    ) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if self.sender_id:
+            headers["X-LCP-Sender-Id"] = self.sender_id
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.hmac_secret:
+            timestamp = utc_timestamp()
+            headers["X-LCP-Timestamp"] = timestamp
+            if idempotency_key:
+                headers["X-LCP-Idempotency-Key"] = idempotency_key
+            headers["X-LCP-Signature"] = sign_hmac(
+                self.hmac_secret, timestamp, idempotency_key, body
+            )
+        elif idempotency_key:
+            headers["X-LCP-Idempotency-Key"] = idempotency_key
+        if test:
+            headers["X-LCP-Test"] = "true"
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        test: bool = False,
+    ) -> dict[str, Any]:
+        body = b""
+        if payload is not None:
+            body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode(
+                "utf-8"
+            )
+            if idempotency_key is None:
+                try:
+                    idempotency_key = message_metadata(payload)["idempotency_key"]
+                except (KeyError, ValueError):
+                    pass
+        headers = self._headers(body, idempotency_key=idempotency_key, test=test)
+        url = f"{self.endpoint}/{path.lstrip('/')}"
+        retryable = method.upper() in {"GET", "HEAD", "PUT", "DELETE", "POST"}
+        last_error: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                with httpx.Client(timeout=self.timeout) as client:
+                    response = client.request(
+                        method,
+                        url,
+                        content=body or None,
+                        headers=headers,
+                        params=params,
+                    )
+            except httpx.RequestError as exc:
+                last_error = exc
+                if not retryable or attempt >= self.max_retries:
+                    raise
+                time.sleep(2**attempt)
+                continue
+
+            try:
+                data = response.json()
+            except ValueError:
+                data = {"raw": response.text}
+            if response.is_success:
+                return data
+            if response.status_code in {429, 500, 502, 503, 504} and attempt < self.max_retries:
+                retry_after = response.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after and retry_after.isdigit() else 2**attempt
+                time.sleep(delay)
+                continue
+            raise LCPHTTPError(response.status_code, data)
+
+        if last_error:
+            raise last_error
+        raise RuntimeError("LCP request failed without a response")
+
+    def submit_lead(self, envelope: dict[str, Any], *, test: bool = False) -> dict[str, Any]:
+        self._validate(envelope)
+        return self.request("POST", "/v1/lcp/leads", payload=envelope, test=test)
+
+    def submit_call(self, envelope: dict[str, Any], *, test: bool = False) -> dict[str, Any]:
+        self._validate(envelope)
+        return self.request("POST", "/v1/lcp/calls", payload=envelope, test=test)
+
+    def submit_bid(self, envelope: dict[str, Any], *, test: bool = False) -> dict[str, Any]:
+        self._validate(envelope)
+        return self.request("POST", "/v1/lcp/bids", payload=envelope, test=test)
+
+    def query_lead_status(self, lead_id: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/lcp/leads/{quote(lead_id, safe='')}")
+
+    def get_schema(self, name: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/lcp/schemas/{quote(name, safe='/')}")
+
+    def get_capabilities(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/lcp/capabilities")
+
+    def list_offers(self, vertical: str | None = None) -> dict[str, Any]:
+        params = {"vertical": vertical} if vertical else None
+        return self.request("GET", "/v1/lcp/offers", params=params)
+
+    def _validate(self, envelope: dict[str, Any]) -> None:
+        if self.validator:
+            self.validator.require_valid_envelope(envelope)

lcp_sdk-1.0.0/lcp_sdk/envelope.py

@@ -0,0 +1,54 @@
+"""Helpers for constructing LCP envelopes."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+def utc_timestamp() -> str:
+    """Return the current UTC time in the canonical LCP format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build_envelope(
+    message_type: str,
+    sender_id: str,
+    receiver_id: str,
+    payload: dict[str, Any],
+    *,
+    version: str = "1.0.0",
+    message_id: str | None = None,
+    correlation_id: str | None = None,
+    idempotency_key: str | None = None,
+    timestamp: str | None = None,
+    test: bool = False,
+) -> dict[str, Any]:
+    """Build a complete LCP envelope around a message payload."""
+    message_id = message_id or str(uuid4())
+    idempotency_key = idempotency_key or f"{sender_id}-{message_type}-{uuid4().hex}"
+    return {
+        "lcp": {
+            "version": version,
+            "message": {
+                "id": message_id,
+                "type": message_type,
+                "timestamp": timestamp or utc_timestamp(),
+                "sender_id": sender_id,
+                "receiver_id": receiver_id,
+                "correlation_id": correlation_id,
+                "idempotency_key": idempotency_key,
+                "test": test,
+            },
+            "payload": payload,
+        }
+    }
+
+
+def message_metadata(envelope: dict[str, Any]) -> dict[str, Any]:
+    """Return the message header or raise for a malformed envelope."""
+    try:
+        return envelope["lcp"]["message"]
+    except (KeyError, TypeError) as exc:
+        raise ValueError("Envelope must contain lcp.message") from exc