Uygulamayı aç
Moonborn — Developers

Ruby SDK

Resmi Ruby Moonborn istemcisi. Deyimsel (idiomatic) snake_case, anahtar kelime argümanları (keyword args), donmuş dize (frozen-string) uyumlu, örüntü eşleşmeli (pattern-match) sonuç hash'leri. Rails / Sinatra için hazır.

moonborn (RubyGems) — resmi Ruby SDK'sıdır. Kanonik OpenAPI belirtiminden üretilir; deyimsel Ruby:

  • snake_case metotlar + anahtar kelime argümanları (keyword arguments)
  • Düz hash'ler (plain hashes) döner (örüntü eşleşmesi için ideal)
  • frozen_string_literal: true uyumludur
  • 5xx + 429 hatalarında otomatik yeniden deneme
  • Rails + Sinatra ile sorunsuz çalışır

Bu sayfayı bitirdiğinde

  • Ruby SDK'sını kurabilecek ve başlatabileceksin.
  • Persona oluşturma + sohbet + akış çağırabileceksin.
  • Örüntü eşleşmesiyle (pattern-match) sonuç hash'lerini ayrıştırabileceksin.
  • Hata işleme (Moonborn::ApiError) ile yeniden-deneme-farkındalıklı kod yazabileceksin.

Ön koşul: Ruby 3.1+, API anahtarı.

Kurulum

gem install moonborn

Gemfile:

gem 'moonborn', '~> 1.0'
bundle install

Başlatma

require 'moonborn'
 
client = Moonborn.new(
  api_key: ENV.fetch('MOONBORN_API_KEY'),
  # base_url: 'https://api.moonborn.co',  # kendi sunucuna kurulum
  # timeout: 60,
  # max_retries: 3,
)

Ortam değişkeni yedeği: MOONBORN_API_KEY.

Persona oluşturma

persona = client.personas.create_persona(
  intent: "İstanbul'dan 34 yaşında bir kurucu. Parlak ama huzursuz.",
  workspace_id: 'ws_...',
  options: {
    pipeline: { audit: { enabled: true } }
  }
)
 
puts persona[:id]
puts persona[:surface][:name][:display]

Sonuç bir hash'tir — persona[:id], persona[:surface][:name][:display]. Örüntü eşleşmesi ile (Ruby 3.0+):

case persona
in { id:, surface: { name: { display: name } }, audit: { score: }, status: 'flagged' }
  warn "Flagged: #{name} (audit #{score})"
in { id:, surface: { name: { display: name } } }
  puts "OK: #{name} (#{id})"
end

Sohbet — akışsız

session = client.chat.create_session(persona_id: persona[:id])
 
reply = client.chat.send_message(
  session_id: session[:id],
  content: 'Seni ne tetikler?'
)
 
puts reply[:content]
puts "Drift: #{reply[:drift_score]}, Alert: #{reply[:drift_alert]}"

Sohbet — akışlı

client.chat.stream_message(
  session_id: session[:id],
  content: 'Sessiz bir gerçek söyle.'
) do |chunk|
  case chunk[:type]
  when 'token'
    print chunk[:delta]
  when 'completed'
    puts "\ndrift: #{chunk[:drift_score]}"
  end
end

Blok stilinde — Ruby-yerel. Yineleyici (iterator) dönen sürümü de vardır:

stream = client.chat.stream_message(session_id: session[:id], content: '...')
stream.each do |chunk|
  print chunk[:delta] if chunk[:type] == 'token'
end

Üretim hattı akışı

client.personas.create_persona_stream(intent: '...') do |event|
  case event
  in { type: 'step.started', step: }
    puts "Başladı: #{step}"
  in { type: 'step.completed', step:, duration_ms: }
    puts "Bitti: #{step} (#{duration_ms}ms)"
  in { type: 'pipeline.completed', persona_id: }
    puts "Persona: #{persona_id}"
  end
end

Hata işleme

begin
  client.personas.get_persona(id: 'per_...')
rescue Moonborn::ApiError => e
  case e.code
  when 'rate_limited'
    sleep(e.retry_after)
    retry
  when 'not_found'
    nil
  when 'validation_failed'
    Rails.logger.error("invalid body: #{e.details}")
    raise
  end
end

14 hata kodunun tümü: Hatalar.

Eşgüçlülük (idempotency)

persona = client.personas.create_persona(
  intent: '...',
  workspace_id: 'ws_...',
  idempotency_key: 'persona-build-2026-05-17-mert',
)

24 saat içinde yeniden gönderilen istekler orijinal yanıtı döndürür. SDK otomatik de üretir.

Rails entegrasyonu

# config/initializers/moonborn.rb
MOONBORN = Moonborn.new(api_key: Rails.application.credentials.moonborn_api_key)
 
# app/services/persona_creator.rb
class PersonaCreator
  def self.create(intent:, workspace_id:)
    MOONBORN.personas.create_persona(
      intent: intent,
      workspace_id: workspace_id,
      idempotency_key: "#{workspace_id}-#{Digest::SHA256.hexdigest(intent)[0..7]}",
    )
  end
end

Otomatik yeniden deneme

İstemci 5xx + 429 hatalarında üstel geri çekilme ile otomatik yeniden deneme yapar:

client = Moonborn.new(
  api_key: ENV['MOONBORN_API_KEY'],
  retry_config: {
    max_retries: 5,
    initial_wait: 0.5,
    max_wait: 30,
  }
)

validation_failed, idempotency_conflict, drift_blocked hataları asla otomatik yeniden denenmez.

Sık karşılaşılan hatalar

"Moonborn::ApiError: unauthorized"

API anahtarı eksik veya geçersiz. ENV['MOONBORN_API_KEY'] doğru çalışma alanını hedefliyor mu kontrol et.

Sürekli rate_limited

Üretimde çalışma alanı planını kontrol et. Detay: Hız limitleri.

Plan gereksinimi

Her plan.

İlgili

TypeScript SDK

Çok dilli (polyglot) ekipler için referans.

Open →
Python SDK

Eşzamanlı ↔ eşzamansız deseni.

Open →
Hatalar

Moonborn::ApiError kod kataloğu.

Open →
Webhook imza doğrulama

Rails uç noktası için HMAC deseni.

Open →