Python SDK
Python 3.10+ için resmi Moonborn istemcisi. Eşzamanlı (sync) + eşzamansız (async — AsyncMoonborn), OpenAPI'den otomatik üretilir, eşgüçlülük (idempotency) + yeniden deneme yerleşik.
moonborn (PyPI) — resmi Python SDK'sıdır. Python 3.10+ üzerinde eşzamanlı ve eşzamansız (AsyncMoonborn) istemciler vardır. Kanonik OpenAPI belirtiminden otomatik üretilir; her API sürümüyle bir hafta içinde yenilenir.
Bu sayfayı bitirdiğinde
- Python SDK'sını kurabilecek ve başlatabileceksin.
- Eşzamanlı (sync) + eşzamansız (async) desenleri arasındaki farkı bileceksin.
- Persona oluşturma + sohbet + akışı uçtan uca çağırabileceksin.
- Hata işleme (
MoonbornAPIError) doğru yakalayabileceksin. - Tür ipuçları (type hints) ve Pydantic modelleri için neye dikkat edeceğini bileceksin.
Ön koşul: Python 3.10+, API anahtarı.
Kurulum
pip install moonborn
# veya
poetry add moonborn
# veya
uv add moonbornBaşlatma — eşzamanlı
import os
from moonborn import Moonborn
client = Moonborn(
api_key=os.environ["MOONBORN_API_KEY"],
# İsteğe bağlı
base_url="https://api.moonborn.co", # kendi sunucuna kurulum için
timeout=60.0, # istek zaman aşımı (saniye)
max_retries=3, # yeniden denenebilir hatalar için
)Ortam değişkeni yedeği: MOONBORN_API_KEY, MOONBORN_BASE_URL otomatik algılanır.
Başlatma — eşzamansız
import asyncio
import os
from moonborn import AsyncMoonborn
async def main():
async with AsyncMoonborn(api_key=os.environ["MOONBORN_API_KEY"]) as client:
persona = await client.personas.create(intent="...")
print(persona.id)
asyncio.run(main())async with bağlam yöneticisi — bağlantı temizliği için önerilir (elle await client.aclose() da çalışır).
Persona oluşturma
persona = client.personas.create(
intent="Bahçeyle takıntılı, İstanbul'da yaşayan emekli bir cerrah.",
options={
"pipeline": {
"audit": {"enabled": True},
"voice_fingerprint": {"enabled": True},
},
},
)
print(persona.id)
print(persona.surface.name.display)
print(persona.audit.score)Alan adları snake_case (Pythonic); JSON'da camelCase olarak gelir ama SDK otomatik dönüşüm yapar.
Akış (streaming) ile üretim
stream = client.personas.create_stream(
intent="Lagos'ta sokak-akıllı bir market satıcısı."
)
for event in stream:
if event.type == "step.started":
print(f"Başladı: {event.step}")
elif event.type == "step.completed":
print(f"Bitti: {event.step}, {event.duration_ms}ms")
elif event.type == "pipeline.completed":
print(f"Persona: {event.persona_id}")Eşzamansız varyantı AsyncMoonborn.personas.create_stream() → async for event in stream.
Sohbet — akışlı
session = client.chat.sessions.create(persona_id=persona.id)
stream = client.chat.messages.stream(
session_id=session.id,
content="Sessiz bir gerçek söyle.",
)
drift_score = 0
for chunk in stream:
if chunk.type == "token":
print(chunk.delta, end="", flush=True)
elif chunk.type == "completed":
drift_score = chunk.drift_score
print(f"\nDrift: {drift_score}")Sohbet — akışsız
reply = client.chat.messages.create(
session_id=session.id,
content="En büyük korkun ne?",
)
print(reply.content)
print(f"Drift: {reply.drift_score}, Alert: {reply.drift_alert}")Eşzamansız akış deseni
async with AsyncMoonborn(api_key=os.environ["MOONBORN_API_KEY"]) as client:
session = await client.chat.sessions.create(persona_id=persona.id)
async for chunk in client.chat.messages.stream(
session_id=session.id,
content="Sessiz bir gerçek söyle.",
):
if chunk.type == "token":
print(chunk.delta, end="", flush=True)Hata işleme
from moonborn import Moonborn, MoonbornAPIError
try:
client.personas.create(intent="...")
except MoonbornAPIError as err:
if err.code == "rate_limited":
time.sleep(err.details["retry_after"])
# yeniden dene
elif err.code == "validation_failed":
print("Body invalid:", err.details["validation_errors"])
elif err.code == "forbidden":
print("Yetki kapsamı / rol eksik")14 hata kodunun tümü: Hatalar.
Eşgüçlülük (idempotency)
persona = client.personas.create(
intent="...",
idempotency_key="persona-build-2026-05-17-mert",
)24 saat içinde yeniden gönderilen istekler orijinal yanıtı döndürür. SDK ayrıca otomatik üretir (UUID).
Tür ipuçları + Pydantic
Tüm SDK yanıtları Pydantic v2 modelleridir:
from moonborn.types import Persona, ChatMessage
persona: Persona = client.personas.create(intent="...")
# Persona.soul, Persona.self, Persona.mask, Persona.surface
# Hepsi türlüdür (typed)
# JSON'a dönüştür
json_str = persona.model_dump_json(indent=2)
# Sözlüğe (dict) dönüştür
data = persona.model_dump()Tür denetleyicisi (mypy, pyright) ve IDE otomatik tamamlama tüm alanları görür.
Geri basınç (backpressure) geri çağırması
def on_rate_limit_near_cap(remaining: int, reset_in: int) -> None:
if remaining < 50:
logger.warning(f"Hız limiti yaklaşıyor: {remaining} kaldı")
client = Moonborn(
api_key=os.environ["MOONBORN_API_KEY"],
on_rate_limit_near_cap=on_rate_limit_near_cap,
)Detay: Hız limitleri.
Sık karşılaşılan hatalar
ImportError: cannot import name 'Moonborn'
Eski sürüm yüklü. pip install --upgrade moonborn ile son sürüme çık.
Eşzamansız kod eşzamanlı istemci kullanıyor
FastAPI, asyncio veya celery'de AsyncMoonborn kullan (eşzamanlı Moonborn olay döngüsünü — event loop — bloklar). Eşzamanlı kod (CLI betiği, Django senkron görünümü) için Moonborn doğrudur.
"Read timed out" akış sırasında
timeout çok düşük. Akış için timeout=None (devre dışı) veya timeout=300.0 (5 dakika):
client = Moonborn(
api_key=os.environ["MOONBORN_API_KEY"],
timeout=None, # akış için
)OpenAPI'den otomatik üretim
SDK kaynağı packages/sdk-py/; OpenAPI 3.1 → openapi-generator ile üretilir. Özel değişiklik istiyorsan kendi istemcini üret (openapi-python-client).
Plan gereksinimi
Her plan.