Python SDK

Use mango_sdk with Python 3.11+. It includes Mango and AsyncMango clients and generated request/response TypedDict types. The distribution name is mango-sdk; the Python import remains mango_sdk.

Install

Install the published alpha in a virtual environment:

python3 -m venv .venv
.venv/bin/python -m pip install 'mango-sdk==0.1.0a1'

This is an alpha with no stable API contract. For development against this checkout, see source installation.

Configure the client

import os

import httpx
from mango_sdk import Mango

client = Mango(
    base_url=os.environ.get("MANGO_BASE_URL", "http://localhost:8080"),
    api_key=os.environ["MANGO_API_KEY"],
    stream_timeout=httpx.Timeout(60.0),
)

Use a context manager or call client.close() when finished. AsyncMango uses async with and awaited operations. Keys authenticate to your Mango server; model-provider credentials stay on the worker. Do not append /v1 to base_url.

Methods and inputs

Operation IDs become snake_case: create_session, send_session_events, and create_memory. Path identifiers are positional; body and query values are keyword arguments. For example, types[] becomes types and created_at[gte] becomes created_at_gte.

Omit a dictionary key to omit a field; None sends explicit JSON null. False, zero, empty strings, and empty lists are preserved. Types guide static checking; server-side validation remains authoritative.

Streaming and pagination

Entering with client.stream_session_events(session_id) establishes the subscription before the next statement. Send input inside that context, then iterate envelopes with event and decoded data fields. Exit closes the stream. The async variant uses async with and async for.

iter_session_events follows pages; list_session_events fetches one page. The stream is live-only; reconnect by opening a stream and reconciling persisted history. The default read timeout for streams is unbounded; the quickstart sets a 60-second read timeout so a stalled example fails visibly.

Errors and retry safety

APIError exposes status_code, type, and request_id. Calls do not automatically retry mutations. A timeout does not prove the server rejected a message; check history before retrying.