Docs · Python SDK

seekmodo-sdk

Server-side Python SDK for the Seekmodo MCP gateway. Bundles the HMAC signer, the three-state circuit breaker, the per-tenant snapshot poller, the mode FSM (off / learning / shadow / active / enforce), the EdDSA pairing handshake, the browser-token mint, the events batcher, and a structured exception taxonomy into a single PyPI package — with full parity to the PHP SDK.

When to reach for this

Use this SDK when you're writing a Django, Flask, or FastAPI storefront connector, an indexing pipeline, or any server-side integration that talks to the gateway with your tenant's HMAC shared secret. For browser code, use the JavaScript SDK — it never sees your shared secret.

Install

pip install seekmodo-sdk

Requires Python >=3.10. Runtime dependencies are httpx and PyJWT[crypto] (Ed25519 pairing verify).

Quick start

from seekmodo_sdk import Client, HmacSigner, CircuitBreaker
from seekmodo_sdk.storage import InMemoryBreakerStore

signer = HmacSigner("your-tenant-id", "your-shared-secret")
breaker = CircuitBreaker(InMemoryBreakerStore())

with Client(signer=signer, breaker=breaker) as client:
    results = client.search({"q": "red sneakers", "per_page": 24})
    client.index(documents, action="upsert")

Public surface

Transport — Client (search, index, events, tenant handshake, tenant snapshot, browser token, tools, health), HmacSigner.
Resilience — CircuitBreaker with pluggable BreakerStateStore (reference: InMemoryBreakerStore).
Per-tenant config — TenantSnapshot polls /v1/tenant.snapshot with stale-while-revalidate caching via CacheProtocol.
Mode FSM — ModeFsm and AutoPromoter mirror the PHP connector lifecycle.
Pairing & events — Pairing, BrowserToken, EventsQueue, and click / impression / search payload builders.

Exception taxonomy

from seekmodo_sdk.exceptions import ClientError

try:
    hits = client.search({"q": keyword})
except ClientError as exc:
    if exc.should_fallback():
        return native_storefront_search(keyword)
    raise

Specialised subclasses: TenantUnavailableError, OverQuotaError, SignatureMismatchError, BreakerOpenError.

Wire contract tests

The SDK ships the same gateway wire-contract fixture pack as the PHP SDK. Run pytest tests/contracts after upgrading to confirm your connector still speaks the canonical envelope.