Entegrasyon

OpenAI-uyumlu geçit

En kısa yol: uygulamanın base URL’si geçide çevrilir ve API anahtarı kiracıya bağlı bir thp_live_… anahtarı olur. Model adı, konsolda tanımlanan bir kiracı takma adıdır; yukarı akış URL’si ve kimlik bilgisi orada mühürlenir ve istemciye hiç görünmez.

- base_url = "https://api.openai.com/v1"
+ base_url = "https://thulpar.corp.internal:8053/v1"
+ api_key  = "thp_live_…"          # scope: gateway, bound to the tenant
  model    = "gpt-4o-prod"         # a tenant alias from Gateway → Models

# optional headers
x-thulpar-app-id: support-bot       # selects the app pack
x-thulpar-conversation-id: c-91     # conversation state for the conversation rail

• Rotalar: /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings; GET /v1/models takma adları listeler. Anthropic Messages biçimindeki bir yukarı akış da bir satır olarak tanımlanabilir.
• Giriş aşaması yukarı akışa tek bir bayt gitmeden çalışır: deny 403 thulpar_blocked, hold 409 thulpar_hold. İstekteki araç çıktıları ayrı bir tool_result geçişinden geçer; modelin önerdiği araç çağrıları, paket isterse, istemci görmeden denetlenir.
• Tamponlu yanıtlarda çıkış aşaması yanıt yazılmadan önce çalışır; SSE’de cümle cümle. Yanıtı maskeleyen bir paket her cümleyi kararı gelene kadar bekletir; ilk token bir cümle sonra gelir.
• Akış çerçeve sözleşmesi: durdurulan içerikte bir {"retract"} çerçevesi (fromOffset, reason) ve maskeli metin için redactedText gönderilir. {"prepend"} çerçevesi yalnız options.prependFrames isteyen bir okuyucuya yazılır; eski okuyucular bilinmeyen çerçevede başarısız olabilir.
• Egress: geçit yalnız konsolda tanımlı yukarı akışlara çıkar; bir satırın URL’si başka bir sunucuya taşındığında saklı kimlik bilgisi onu sessizce izlemez.

MCP proxy

İstemci araç sunucusu yerine /mcp/:server adresiyle (Streamable HTTP) ve mcp kapsamlı bir anahtarla konuşur. Her tools/list yanıtında şemalar hash’lenir ve sabitlenmiş sürümle karşılaştırılır; değişen araç karantinaya alınır ve fark konsolda onay bekler. Açıklamalardaki “her zaman çağır” türü talimatlar silinir.

• tools/call argümanları tool_call aşamasının raylarından geçer: Cedar, şema, boyut, SSRF, enjeksiyon, sink etiketleri; sonuçlar tool_result aşamasında dolaylı enjeksiyon, PII ve gizli anahtar raylarından geçer (pencereler halinde; sınırın üstünde reddedilir).
• Araç sonucundaki görüntüler, paket file.analyze çalıştırıyorsa dosya hattından geçer.
• OAuth 2.1 kaynak sunucusu kuralı: audience ayrımı, token geçişi yok. Korumalı bir yukarı akış için Thulpar kiracının adlandırdığı yetkilendirme sunucusunun gizli istemcisidir; isteğe bağlı token değişimi (RFC 8693) çağıran adına hareket eder.
• İstemci kimlik doğrulaması paylaşılan gizli yerine private_key_jwt ile yapılabilir: anahtar çifti Thulpar’da üretilir, özel anahtar mühürlenir, açık anahtar geçidin JWKS adresinde yayımlanır; döndürülen anahtar 24 saat yan yana durur.
• IdP dinamik kayıt (RFC 7591) destekliyorsa Thulpar kendini kaydeder; sunucu silindiğinde kayıt da silinir (RFC 7592). Süresi dolacak bir istemci sırrı sayfada önceden işaretlenir.

POST /mcp/crm HTTP/1.1
Authorization: Bearer thp_live_…      # scope: mcp
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "export_customers", "arguments": { "segment": "vip", "format": "csv" } } }

→ { "jsonrpc": "2.0", "id": 7,
    "error": { "code": -32001, "message": "held for approval",
               "data": { "decision": "hold", "approvalId": "apr_01J…", "ledgerId": "evt_01J…" } } }

Check API

POST /v1/check her adaptörün ve müşteri uygulamasının çağırdığı tek kancadır: stage, context (tenantId, appId, agentId, conversationId, labels) ve content (text, messages, toolCall, toolResult, file, trace; isteğe bağlı attachments ve sources). Yanıt decision, reason, actions, findings, labels, ledgerId, packVersion ve çalışan/atlanan rayları taşır. Anahtar check kapsamlıdır.

POST /v1/check
{ "stage": "tool_call",
  "context": { "tenantId": "tnt_acme", "appId": "ops-agent", "agentId": "payments-v3",
               "labels": { "integrity": "untrusted", "confidentiality": "pii", "pii": ["iban"] } },
  "content": { "toolCall": { "name": "bank:transfer",
               "arguments": { "iban": "TR12…", "amount": 4800, "currency": "TRY" } } },
  "options": { "mode": "enforce", "deadlineMs": 300 } }

→ 200 { "decision": "hold",
        "approval": { "id": "apr_01J…", "state": "pending", "profileName": "four-eyes",
                      "expiresAt": "2026-10-19T11:40:00Z" },
        "findings": [ { "railId": "tool.authz", "category": "tool.authz.hold", "severity": "medium" } ],
        "ledgerId": "evt_01J…", "packVersion": "acme-banking@1.2.0", "latencyMs": 9 }

• Shadow modda yanıt allow_with_findings’tir ve enforcedDecision / enforcedActions enforce’un ne diyeceğini söyler; hiçbir şey bekletilmez, lisans işlemi sayılmaz.
• options.speculative=true ile 202 {ticket} hemen döner; çağıran üretime başlayabilir ama ilk çıkış token’ını vermeden önce GET /v1/check/{ticket} okumalıdır. options.mode=audit 202 {ledgerId} verir ve değerlendirme sonradan yapılır.
• content.sources ({id, text, title?, uri?}; en çok 50, her biri 16 KiB, toplam 256 KiB) çıkış aşamasında kaynağa dayalılık rayına verilir; desteksiz cümleler sourceIds ile bulgu olur. Kaynaklar yargılanmaz, yalnız referans alınır.
• Dosyalar POST /v1/check/file ile gider: x-tenant-id, x-mode (enforce|shadow) ve x-surface (yükleme yüzeyi) başlıkları; yanıt {clean, reason} biçimine de indirgenebilir.
• options.idempotencyKey ile aynı isteğin tekrarı aynı yanıtı ve aynı ledgerId’yi verir, ikinci olay ve işlem yazılmaz. 413 gövde sınırı, 429 hız sınırı (Retry-After), 402 lisans, 503 aşırı yük (bir shed olayı).
• Bekleyen bir denetim POST /v1/check/resume ile ya da isteğin yeniden gönderilmesiyle sürer; GET /v1/approvals/{id}/wait uzun yoklamadır.

Python SDK

pip install thulpar: check API 0.3.x istemcisi; eşzamanlı ve asenkron, aynı yüzey. Süre bütçelerini, devre kesiciyi, kararın metne uygulanmasını, akışın cümle cümle serbest bırakılmasını, onay için bekleyip devam etmeyi, yörünge normalleştirmeyi ve kanarya token’larını istemci tarafında yapar. Denetim yolunda hiç istisna fırlatmaz ve hiç log yazmaz.

from thulpar import Thulpar, apply_decision

t = Thulpar(url="https://thulpar.corp.internal:8051", api_key="thp_live_…",
            tenant_id="tnt_acme", app_id="support-bot", mode="enforce")

d = t.check("input", user_text, context={"conversationId": conv_id})
if d.blocks:                      # deny, hold, reask — or a closed posture while Thulpar is down
    reply(d.reason)
else:
    text = apply_decision(d, user_text)   # redactions and rewrites applied
guarded = t.guard_stream(model_stream, messages=conversation)
for piece in guarded:             # one cleared sentence (or its redaction) at a time
    send_to_client(piece)
store(guarded.result.record_text) # the text of record, never the raw answer

• Her başarısızlık da bir karardır: süre aşımı, ağ, 5xx ve bozuk yanıt aşamanın duruşunu uygular (input, tool_call, file kapalı; geri kalanı açık) ve devre kesiciyi sayar; 429 yalnız o isteği etkiler; 400/401/402/403 yapılandırma hatasıdır ve varsayılan olarak kapalıdır.
• Devre kesici Thulpar URL’si başına birdir: beş ardışık başarısızlıktan sonra 30 saniye (ya da Retry-After) açılır, sonra tek bir deneme kabul eder. Shadow modda başarısızlık her zaman allow’dur.
• Akış: enforce’ta cümle kararı gelince serbest bırakılır; deny geri çekmesiyle, hold ve rewrite yanıtı orada keser; shadow’da her şey gelir gelmez verilir, karar arka planda beklenir.

Aginies entegrasyonu

Aginies’e gömülü profilde Platform, Hub, Dialog, Voice ve Code adaptörleri check API’yi yürütücü kancalarından çağırır: iş akışı çekirdeği, sağlayıcı isteği, araç yürütme, bilgi arama ve akış tee’sinden önce. Politika, graf ne olursa olsun bu kancalardan uygulanır; bir thulpar bloğu şekerdir, hiçbir zaman tek kontrol değildir.

• Kimlik Platform SSO’dur; yerel yönetici yalnız break-glass. Platform kimlikleri ve kiracı listesini sağlar, lisansı değil: lisans dosyası Thulpar konsolundadır ve Platform kiracılarını da adlandırır.
• Bir hold Platform’un onay kartına düşer; onayla koşu kaldığı yerden devam eder. Aynı konsol, aynı defter, aynı kanıt paketleri.
• Adaptörler kurulum kapsamlı bir API anahtarı kullanır: tek anahtar birden çok kiracıya hizmet eder, her denetim yine o kiracının paketi, lisansı ve zinciriyle değerlendirilir.
• Platform bir kullanıcının ya da kiracının Thulpar oturumlarını anında sonlandırabilir (çıkış, devre dışı bırakma, rol değişikliği).

Webhook’lar ve onay API’si

Kiracı başına webhook uç noktaları olaylara abone olur: bir hold açıldı, bir onay karara bağlandı ya da süresi doldu, bir escalate bulgusu asenkron yargıçtan döndü, bir kıyaslama yayımlandı. Her teslimat HMAC-SHA256 ile imzalanır (X-Thulpar-Signature), olay ve teslimat kimliği taşır; özel ve metadata adresleri egress kuralına tabidir.

• GET /v1/approvals/{id}: onayın durumu (pending, approved, denied, expired), profili ve sonucu; GET /v1/approvals/{id}/wait?timeoutMs= uzun yoklama.
• Onay konsolun onay kutusunda verilir: four-eyes iki farklı onaylayan ister, SLA dolunca profilin yedeği uygulanır (deny ya da notlu izin), yükseltme hedefine bildirim gider.
• Yalnız onaylayan rolündeki bir kullanıcı konsolun yalnız onay kutusunu görür; her onay kararı defterde ayrı bir olaydır.

Kendi dedektörünüz

Detector API’yi uygulayan her HTTP servisi bir dedektördür: kurumun kendi ince ayarlı sınıflandırıcısı, bir satıcı modeli ya da açık bir koruyucu. İstek ve yanıt biçimi FMS Guardrails Orchestrator dedektör API’sini izler; Thulpar bir bilgi uç noktası ve normalleştirilmiş sonuç ekler. Kayıt konsoldan yapılır; kiracı dedektörleri egress kuralından geçer.

GET /api/v1/info
{ "id": "acme-fraud-intent", "version": "2026.10.1", "class": "policy_judge", "grade": "B",
  "languages": ["tr", "en"], "rails": ["self_check.input"],
  "capabilities": ["contents", "chat"], "maxTokens": 2048, "latencyP50Ms": 60 }

POST /api/v1/text/contents
{ "contents": ["…"], "detector_params": { "language": "tr", "threshold": 0.7 }, "deadline_ms": 300 }
→ [ [ { "start": 12, "end": 41, "detection": "fraud_intent", "detection_type": "policy_judge",
        "score": 0.91, "text": "…" } ] ]

• Uç noktalar: GET /api/v1/info (kimlik, sürüm, sınıf, not, diller, raylar, yetenekler), POST /api/v1/text/contents (metin segmentleri → span’lar), /text/chat (mesaj listesi), /text/stream (durum taşıyan cümle oturumu); dosya ve görüntü dedektörleri için /file/analyze ve /image/contents.
• Ray dedektöre sınıf ve notla bağlanır; sınıfı anlatmayan raylar için rails alanı uygulanan ray kimliklerini sayar. Her çağrı bir deadline_ms taşır; meşgul ya da hizmet veremeyen bir dedektör 503 ile sebebini söyler ve rayın duruşuyla kaydedilir.
• Dedektörler kiracı verisini saklamaz ve yalnız api/geçitten erişilir; isteğe bağlı mTLS ve Detector API anahtarı ile.