Skip to content

Build with Palo

Serviceable SDKs

The SDK is a typed convenience layer over the Mpalo HTTP API. It validates common inputs, resolves credentials, sends request identifiers, parses the response contract, and exposes both raw and structured values where that is useful for an application.

Client lifecycle

Instantiate one client per application configuration and reuse it. Configure the API key through a secret manager or environment variable. Set an explicit base URL only for a controlled test environment. Configure timeout and retry behavior for your workload, then close the client when the language runtime requires it.

from palo import Palo

client = Palo(
    api_key="your-api-key",
    timeout=30,
    max_retries=2,
)

health = client.infrastructure.health()
print(health.status, health.execution_mode)

The package also contains a compatibility PaloClient and AsyncPaloClient surface. Use it for existing integrations while moving new code to the versioned resource surface documented here.

Memory API

The versioned resource is client.memory. It exposes write, recall, and delete for the infrastructure v1 contract. The memory store connection is configured on the API key or account. The request does not select an arbitrary external LLM and cannot cross tenant scope.

write = client.memory.write(
    "The user prefers a quiet workspace.",
    namespace="preferences",
    idempotency_key="preferences-user-42-1",
)

if write.decision.get("memorized"):
    related = client.memory.recall(
        "What kind of workspace does the user prefer?",
        namespace="preferences",
        top_k=3,
    )
    print(related.context)

deleted = client.memory.delete(namespace="preferences")
Inspect the state.

Check write.state, write.decision, write.provenance, and write.usage. Recall exposes retrieval_outcome and proximity. Do not treat an accepted request as proof that memory was retained.

Retries, idempotency, and errors

Only retry a write when its request is safe to repeat. Supply the same idempotency key for every retry of the same logical event. Preserve the request ID in logs and support tickets. The SDK raises typed errors for authentication, validation, conflicts, rate limits, timeouts, connection failures, and server responses.

SituationClient behavior
Validation failureFix the request. Do not retry unchanged input.
401 or 403Refresh or replace credentials, then verify storage attachment and account permission.
409 with an idempotency keyRead the conflict and decide whether the original request already completed.
429 or retryable 5xxUse bounded exponential backoff and respect server guidance.
Timeout or connection errorRetry only with the same idempotency key for a write, and keep the original request ID if known.

Import boundary

The current SDK surface has no separate bulk-import endpoint. Import preparation can run locally, while committed records use the same versioned memory write path as native application events. Mark imported records with source.type="imported_archive", preserve the source timestamp when it is valid, and reuse stable idempotency keys on retries.

The Python migration reference shows the supported pattern. The CLI has no bulk migration command yet. It can submit individual records with palo memory write. No import path selects a model or delegates extraction to an external LLM.

Language guides and integrations

Python

The supported typed client with sync and async resource surfaces.

HTTP

Use the versioned contract from any language or runtime.

CLI

Operate the same resources interactively or as JSON automation.

Framework adapters should pass memory context into your application model call. Mpalo does not represent the external model call, provider key, prompt policy, or output as part of the memory API contract.