humane-ai 0.3.1

Behavioral intelligence for your LLM apps. Every AI should know who it's talking to.

Humane AI SDK

Behavioral intelligence layer for LLM applications. One line to make your AI emotionally aware, relationally continuous, and safety-gated.

Install

pip install humane-ai

Quick Start

from humane_ai import HumaneClient

client = HumaneClient(api_key="hx_your_key")

# Single message
response = client.process("user_123", "I need help with my order")
print(response.response)           # AI response shaped by behavioral context
print(response.user.mood)          # 0.35 — frustration detected
print(response.context.empathy)    # 0.95 — auto-increased
print(response.timing.delay_ms)    # 400  — faster for urgent user
print(response.safety.action)      # PROCEED

# Multi-turn (history auto-managed)
client.process("user_123", "My name is Sarah, I work at TechCorp")
r = client.process("user_123", "Do you remember my name?")
# AI responds: "Yes, you're Sarah from TechCorp"

# Check behavioral state
if response.user.is_frustrated:
    print("User needs extra care")

# Proactive triggers
if response.proactive:
    for event in response.proactive:
        print(f"TRIGGER: {event.trigger} — {event.suggested_action}")

# Reading the analysis payload (mirrors the JS SDK exactly since 0.4.0)
a = response.analysis
if a:
    print(a.signal_magnitude)         # "normal" | "strong" | "pivot"
    print(a.mood_delta, a.energy_delta)
    for tg in a.triggers:
        print(f"  {tg.phrase} → {tg.emotion} ({tg.polarity})")
    for reason in a.reasons:
        print(f"  why: {reason}")

# Safety detail
print(response.safety.action)         # PROCEED | HOLD | BLOCK
for m in response.safety.matched:
    print(f"  matched {m.phrase} ({m.category})")
print(response.safety.override)       # e.g. "combo_a_force_block" or None

# A/B experiment assignments for this request
for ex in response.experiments:
    print(f"{ex.experiment_name}: variant {ex.variant_name}")

# Streaming
for event in client.stream("user_123", "Explain how engines work"):
    if event["type"] == "token":
        print(event["data"]["content"], end="", flush=True)