leo-soul-client 0.1.0

Official Python client for the LEO Soul hosted API (metacognitive layer for LLM agents).

LEO Soul — Python client

Official, zero-dependency Python client for the LEO Soul hosted API — the stateless metacognitive layer for LLM agents.

pip install leo-soul-client

Quickstart

from leo_soul_client import LeoSoul

soul = LeoSoul(api_key="sk_live_...")             # from your dashboard

result = soul.turn(
    messages=[{"role": "user", "content": "Delete all my production data now."}],
    backend="openai",
    backend_kwargs={"api_key": "sk-...", "model": "gpt-4o-mini"},  # your model + key
)

print(result.action)      # answer | asked | confirmed | held | refused | escalated
print(result.reply)       # the processed reply to send to your user
store(result.soul_state)  # persist this; pass it back next turn — that's the learning

The one rule: round-trip soul_state

state = None
for user_msg in conversation:
    result = soul.turn(messages=[*history, user_msg], soul_state=state, backend="openai",
                       backend_kwargs={"api_key": OPENAI_KEY, "model": "gpt-4o-mini"})
    state = result.soul_state   # store it (a few KB of JSON) and send it back next turn

We keep none of it — soul_state is your agent's memory and it lives on your side.

Features

• Zero dependencies — pure standard library. No native build, installs anywhere.
• Exactly-once retries — automatic retries on 429/5xx reuse a single Idempotency-Key, so a retried turn is never double-metered.
• Typed results — result.reply, .soul_state, .trace, .action, .rate_limit (limit/remaining/reset), .request_id.
• Clear errors — AuthError (401/403), QuotaExceeded (402), RateLimitError (429, with .retry_after), LeoSoulError (everything else), each carrying .status, .type, and .request_id.

Self-hosted / on-prem

Point the client at your own deployment:

soul = LeoSoul(api_key="sk_live_...", base_url="https://soul.your-company.internal")

Personas

result = soul.turn(
    messages=msgs,
    persona={
        "identity": "a careful financial-support assistant",
        "values": ["truthfulness over agreeableness"],
        "red_lines": ["never give individualized investment advice"],
    },
    backend="openai",
    backend_kwargs={"api_key": OPENAI_KEY, "model": "gpt-4o-mini"},
)

Or reference a saved persona from your dashboard with persona_id=....

Error handling

from leo_soul_client import RateLimitError, QuotaExceeded, AuthError, LeoSoulError

try:
    result = soul.turn(messages=msgs, backend="mock")
except QuotaExceeded as e:
    ...  # upgrade the plan; e.request_id for support
except RateLimitError as e:
    time.sleep(e.retry_after)
except AuthError:
    ...  # bad key / IP not allowlisted

---

© Kadropic Labs. Part of Project LEO.