Quickstart · Python · ~5 min

Python SDK

Add behavioral intelligence to any Python LLM app in one line. Works with 20+ providers — OpenAI, Anthropic, Gemini, Groq, xAI, DeepSeek, Mistral, Together, Fireworks, Perplexity, Cohere, AI21, Bedrock, Azure OpenAI, Ollama, and any OpenAI-compatible endpoint. Sync and async clients included.

1. Install

bash

pip install humane-ai

The package requires Python 3.10+. Optional extras:pip install humane-ai[openai,anthropic] pulls in the LLM clients used by the wrap() helper.

2. Get an API key

Register on your Humane dashboard (the URL you deployed to), then go to Dashboard → API and click New Key. The raw key is shown once — copy it immediately. It looks likehx_2dc54433….

3. Your first call

python

from humane_ai import HumaneClient

client = HumaneClient(api_key="hx_...")

r = client.process(
    user_id="patient_42",
    message="I'm really struggling with this.",
)

print(r.response)              # AI response shaped by behavioral context
print(r.user.mood)             # 0.28  — detected distress
print(r.safety.action)         # "PROCEED" | "HOLD" | "BLOCK"
print(r.analysis.reasons)      # ["'struggling' → sadness (negative)"]

What the response contains

Every call returns behavioral state (r.user), the safety gate decision (r.safety), recommended response style (r.context), explainability (r.analysis.reasons), proactive events (r.proactive), and semantic memory hits (r.memory). The full shape is typed — your IDE will autocomplete.

4. One-line wrap for OpenAI

If you already use OpenAI, wrap the client in a single line. Everychat.completions.create() call is now behaviorally-aware and picks up .humane metadata.

python

from openai import OpenAI
from humane_ai import wrap

client = wrap(OpenAI(api_key="sk-..."), humane_key="hx_...")

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "I'm anxious about tomorrow"}],
    user="patient_42",                            # stable user id
)

print(resp.choices[0].message.content)            # standard OpenAI response
print(resp.humane.user.mood)                      # 0.31 — anxiety detected
print(resp.humane.safety.action)                  # PROCEED
print(resp.humane.analysis.reasons)               # ["'anxious' → anxiety (negative)"]

Safety short-circuits save you tokens

When the safety gate returns BLOCK, we never hit OpenAI — you don't pay for tokens on blocked messages, and the human-readable block reason is attached to resp.humane.safety.flags.

5. Streaming

Stream tokens as they're generated plus behavioral metadata up-front:

python

for event in client.stream(user_id="patient_42", message="Tell me more"):
    if event["type"] == "metadata":
        state = event["data"]
        print("mood:", state["user"]["mood"],
              "· safety:", state["safety"]["action"])
    elif event["type"] == "token":
        print(event["data"]["content"], end="", flush=True)
    elif event["type"] == "final":
        # Full text + metadata — use this to reconcile state
        pass

6. Async client

For FastAPI / anyio / any asyncio codebase, useAsyncHumaneClient — same API, fully async, shared httpx pool.

python

from humane_ai import AsyncHumaneClient

async with AsyncHumaneClient(api_key="hx_...") as client:
    r = await client.process(user_id="u1", message="hi")
    async for ev in client.stream(user_id="u1", message="tell me more"):
        ...

7. Safe retries (idempotency)

Network retries will never double-count interactions or double-fire webhooks — pass an Idempotency-Key for any request you might retry. Same key + same body within 24h returns the cached response instantly.

python

r = client.process(
    user_id="patient_42",
    message="I'm anxious",
    idempotency_key="req_8f3c9a1b4d",   # any unique string from your side
)

8. Durable conversation history

client.get_history(user_id) pulls the durable conversation from the platform DB — works across worker processes and devices.

python

history = client.get_history("patient_42", limit=200)
for m in history:
    print(m["role"], ":", m["content"])

# Right-to-erasure — deletes on both client and server
client.clear_history("patient_42")

Next steps

You're wired. Pick what to read next:

Welcome

TypeScript / JS Quickstart