# Python SDK tam başvuru Güncel SDK paketindeki tam kullanım sözleşmesi: kurulum, bütün açık yüzeyler, sınırlar ve hata davranışı. Kaynak metnin dili korunmuştur. ## Paket ve temel kullanım Sigillum Finans Python SDK 0.11.0 Python 3.10+ için normal wheel paketi. `opentelemetry-api`, `opentelemetry-sdk`, `httpx` ve `cryptography` zorunlu bağımlılıklardır. Kurum ekibinin bir yardımcı servis geliştirmesi veya kurması gerekmez. Kurumdaki Sigillum ürün kurulumu dayanıklı aktarımı kendi bileşeniyle sağlar. ```sh python -m pip install sigillum_finans_sdk-0.11.0-py3-none-any.whl ``` Portal/ürün tarafından hedef **servis** için üretilen `config.json` dosyasını sabit uygulama konumuna koyun. Başlatma işlemine mutlak dosya yolunu verin. Yapılandırma çalışma dizininde aranmaz; dosya yalnız arka plan işçisinde okunur. ```python from pathlib import Path from sigillum_finans import start sdk = start(Path(__file__).resolve().parent / ".sigillum" / "config.json") app = sdk.wrap_asgi(app) # FastAPI/Starlette ve standart ASGI HTTP sınırı ``` Bu bağlantıdan sonra, yapılandırılmış gerçek HTTP girişleri ve bu işlem içindeki HTTPX istemci çağrıları otomatik yakalanır. Mevcut HTTPX istemcileri de kapsam içindeki çağrılarda çalışır; ayrıca profil dosyası gerekmez. ASGI uygulama ve HTTPX taşımaları kaynak davranışlarını korur. HTTPX 0.27/0.28 ile standart ASGI HTTP mesaj sınırı desteklenir; websocket, keyfi socket, başka HTTP istemcileri veya görünmeyen model iç adımları otomatik yakalanmış sayılmaz. Diğer sınırlar aşağıdaki ortak hazır yüzeyi kullanır. Uygulamanın okumadığı gelen istek yalnız gerçek HTTP/1.0 veya HTTP/1.1 çerçevelemesi gövde olmadığını kanıtlarsa eksiksiz boş sayılır: Transfer-Encoding bulunmamalı; Content-Length bulunmamalı veya tek geçerli sıfır uzunluk olmalıdır. Sonlandırmada gözlenmiş bayt/parça veya yakalama kaybı da bulunmamalıdır. HTTP metodu tek başına boş gövde kanıtı değildir. Tekrarlı, çelişkili veya geçersiz başlıklar, HTTP/2, HTTP/3 ve bilinmeyen protokol bilgisi doğal tüketim tamamlanmayı kanıtlayana kadar eksik kalır. SDK bu karar için isteği okumaz, boşaltmaz veya geri sarmaz. HTTP girişi olmayan batch/worker hizmetinde ürün tanımındaki gerçek çalıştırma adını kullanın: ```python with sdk.start_execution("daily-calculation"): run_existing_work() ``` Geçerli taşınmış Sigillum bağlamı yoksa giriş, `entryPoints` içindeki tür, işlem adı ve varsa HTTP yolu ile birebir eşleşmelidir. Eşleşme yoksa uygulama veya işlem sahibi tahmin edilmez. Ortak servisin ayarı ilk kullanan uygulamaya sabitlenmez; uygulama sahibi imzalı gerçek kök bağlamından gelir. Portal yapılandırması `sigillum.sdk-config/2` biçimindedir. Her başlangıç tanımı, uygulamanın izlenecek servislerini ve tanım sürümünü içeren imzalı bir `scopeToken` taşır. Ortak servis yalnız o işlemin sabitlenmiş kapsamındaysa kayıt üretir. Kapsam dışındaysa gelen işlem/trace/üst adım ilişkisini aynen aktarır; kendisi için adım veya kayıt oluşturmaz. Başka bir uygulama aynı ortak servisi kullanmaya başladığında ortak servisin ayarına uygulama eklenmez ve SDK yeniden kurulmaz. SDK, başlangıç tanımlarını kurum içindeki Sigillum aktarım adresinden ayrı bir arka plan işçisiyle 30 saniyede bir yeniler. İstek bu yenilemeyi beklemez. Hatalı, geri sürümlü veya eksik bir yanıt geçerli tanımı değiştirmez. Başlamış işlemler kendi imzalı kapsamlarıyla devam eder. Paket ve yapılandırma aynı SDK nesline ait olmalıdır; önceki yapılandırma biçimi sessizce kabul edilmez. ## Ürünün yerel aktarım ajanı Ürün kurulumu aynı makinedeki Sigillum aktarım ajanını sağlıyorsa mevcut `sigillum.sdk-config/2` dosyasına şu isteğe bağlı bölüm eklenir; diğer kimlik, imzalı kapsam ve güven alanları korunur: ```json "localTransfer": { "endpoint": "http://127.0.0.1:29520", "token": "PRODUCT_INSTALLER_GENERATES_A_LOCAL_TOKEN" } ``` Yerel adres yalnız `http://127.0.0.1:` biçimindedir; başka makine, `localhost`, IPv6, path, query, fragment veya kullanıcı bilgisi kabul edilmez. Token, ürün kurulumunun ürettiği 32–256 ASCII karakterdir (33–126; boşluk yok). Proxy ortam değişkenleri ve HTTP yönlendirmeleri kullanılmaz. Bu modda SDK'nın kendi işçisi, aynı gerçek execution ve sabitlenmiş kapsamın hazır gözlemlerini `SFRAW001` olarak yalnız `/v1/captures` adresine gönderir. Metadata özgün envelope'u `content` alanı olmadan, gerçek kök kabulünü ve ek tanımlarını taşır; JSON sayı tokenları ve ek byte'ları aynen korunur. İçerik hash/ref üretimi, `SFREC001`, şifreli custody ve uzak teslim ürün ajanına aittir. Hazır paket en fazla 16 kayıt/8 MiB'dır; büyük geçerli tek kayıt 32 MiB paket sınırında tek başına gider. Başlangıç profilleri yalnız aynı ajanın `/v1/profiles` adresinden alınır ve mevcut bağımsız kapsam imzasıyla doğrulanır. SDK RAM kopyasını yalnız delivery kimliği, ham paket SHA-256'sı ve exact kayıt sayısına bağlı `sigillum.local-handoff/1` HMAC onayı sonrasında bırakır. `local_durable_records`, ajanın kalıcı teslim aldığı kayıt sayısıdır; `custody_accepted` uzak custody kabulü gibi artırılmaz. Ajan kapalıysa veya onay geçersizse aynı paket aynı kimlikle sonlu RAM bütçesinde tekrar denenir; SDK uzak sunucuya doğrudan dönmez. Kurum işi bu denemeleri beklemez. Yerel modda yeniden deneme işçide, ilk yapılandırılmış gecikmeden başlayarak üstel artar ve küçük jitter kullanır. Üst sınır 30 saniyedir; yapılandırılmış ilk gecikme 30 saniyeden büyükse kendi değeri üst sınır olur (en fazla 300 saniye). Başarılı teslim o paketin yeniden deneme durumunu temizler. Doğrudan uzak teslim modunun mevcut gecikme davranışı değişmez. `localTransfer` yoksa mevcut doğrudan HTTPS/SFREC yolu ve P-256 custody makbuzu davranışı aynen devam eder. Yerel ajan kurum ekibinin yazacağı bir yardımcı servis değildir; Sigillum ürün bileşenidir. ## Ek bilgi ve özel AI sınırı SDK bütün dillerle aynı yedi aileyi sunar: `lifecycle`, `ai`, `http`, `otel`, `context`, `source`, `custom`. `ai` içinde model/parametre/sürüm, giriş/çıkış, sınıf/niyet/puan, retrieval/belge/ağırlık/sıra, araç aday/seçim/argüman/sonuç, embedding, inference, değerlendirme, politika ve kaynakta var olan açıklama alanları JSON nesnesiyle verilebilir. Bunlar iş senaryosuna özel sınıflara bağlanmaz. ```python from sigillum_finans import Attachment, JsonData with sdk.start_step("actual-inference") as step: step.observe("ai", "inference.features", JsonData.raw(original_features_json)) result = existing_inference() step.observe("ai", "inference.completed", JsonData.raw(original_result_json)) step.observe("source", "comparison.source", JsonData.raw(original_source_metadata), attachments=(Attachment("original", original_bytes, purpose="comparison.originalContent"),)) ``` `JsonData.raw` mevcut `str` veya değişmez `bytes` JSON nesnesini alır. Kaynak JSON sayıları yuvarlanmaz, açık `null` ve bulunmayan alan birbirine çevrilmez. Ekler özgün byte içerikleridir. Keyfi canlı uygulama nesnesi/getter/iterator taranmaz. Ham JSON doğrulaması ve taşıma kodlaması işçi tarafında yapılır. Eksik/geçersiz/kapasiteyi aşan gözlem sayaca yansır; tam kayıt diye sunulmaz. Mevcut çağrıyı tek kez çalıştıran hazır sınır da kullanılabilir: ```python result = sdk.call_ai("actual-model", JsonData.raw(input_json), existing_call, output=lambda value: JsonData.raw(value.original_json)) # async çağrı için await sdk.call_ai_async(...) kullanılır. ``` Kaynak çıktısı JSON `str`/`bytes` ise `output` seçicisi gerekmez. Diğer çıktı türlerinde gerçek ham JSON'u veren kısa bir seçici kullanın. Seçici gözlem içindir; seçici hatası gerçek çağrının dönüşünü veya hatasını değiştirmez. Stream/tembel çıktılar bu yöntemle önceden tüketilmez. Özel stream sınırında gerçek tüketimde `observe` çağrısı kullanın. Otomatik HTTP stream yakalama yalnız doğal okuma/yazma sırasında gerçekleşir ve 64 KiB parçalar gönderir. ## İsteğe bağlı referanslar ve taşınabilir bağlam ```python from sigillum_finans import References, ExternalReference sdk.set_references(References(session_ref="institution-session-reference", person_ref="institution-person-reference", external=(ExternalReference("native.trace", "source-id"),))) carrier = sdk.export_context() # SDK'sız asenkron taşıyıcı aynı değeri değişmeden taşıyabilir. with sdk.start_execution("continuation", carrier=carrier): continue_existing_work() ``` Oturum ve kişi referansları isteğe bağlıdır; işlem bağlantısı bunlara dayanmaz. Kimlikler kurumda üretilmiş uygun referanslar olmalıdır; login tokenı gerekmez. `inject(headers)` yalnız `x-sigillum-context` ekler. Var olan Sigillum başlığını ve kurumun `traceparent`/`tracestate` değerlerini değiştirmez. Çelişki sayaca yazılır. HTTPX bu başlığı kapsam içindeki çağrıda otomatik taşır. İmzalı taşıyıcının bütünü silinmişse SDK eski kökü tahmin etmez. İsteğe bağlı referanslar 16 KiB taşıyıcı sınırını aşarsa yalnız taşınacak referans nesnesi boşaltılır; gerçek işlem/trace/span kimlikleri yeni MAC ile eksiksiz taşınır. Kaynak bağlamı ve kayıtlar tam referanslarını korur. `referencePropagationPartial` sayacı bu kısmi metadata aktarımını açıklar; referansların rastgele bir alt kümesi veya sahte tamamlanmış aktarım sunulmaz. ## Dahili OTEL ve çalışma davranışı Resmî OTEL, bağımsız `ALWAYS_ON` provider ve yalnız kuyruğa kabul yapan span işleyicisiyle paketin içindedir. Kurumun global provider, sampler, exporter ve mevcut OTEL bağlamı değiştirilmez. SDK'nın gerçek span kimliği kendi süreç kaydına bağlanır; kaynak/araç olayları ikinci bir iş adımı gibi çoğaltılmaz. Kaynak, instrumentation scope, nitelik, olay, link, durum ve gerçek drop sayaçları korunur. Native OTEL kaydında `observerContext` gerçek ürün trace/span/parent bağını, `nativeContext` ise resmî provider'ın gerçek trace/span/parent kimliklerini açıkça taşır. Aynı olduklarında da iki alan bulunur; farklı kimlikler aynı kimlikmiş gibi sunulmaz. Hazır işlem span'ına ilave gerçek teknik bilgi için `operation.set_otel_attribute(name, primitive)` ve `operation.add_otel_event(name, primitive_dict)`, `operation.add_otel_link(trace_id, span_id, primitive_dict)` kullanılabilir. `start`, `observe`, `start_execution`, `start_step`, referans/bağlam yöntemleri ve `close` gözlem ağı, disk, teslim onayı veya flush beklemez. Arka plan işçisi aynı delivery kimliği ve aynı paket byte'larıyla tekrar dener. RAM girdisi yalnız ayrı sabitlenmiş P-256 anahtarının imzaladığı, tam kapsam/paket/kayıt bağları doğrulanmış kalıcı aktarım makbuzundan sonra kaldırılır. SDK kendi aktarım HTTP çağrısını gözlemlemez. `sdk.status`: `state`, `accepted`, `custody_accepted`, `local_durable_records`, `lost`, `pending_records`, `pending_bytes`, `last_error` sunar. `accepted` RAM kabulüdür; kalıcılık iddiası değildir. Ürün aktarımı ilk kalıcı kabulü sağlar. Süreç ilk kalıcı kabulden önce kapanırsa RAM kaybı mümkündür. Sınırlı kapasite dolduğunda kurum işi bekletilmez; gözlem kaybı sayılır ve sonraki bağlı kapsamda raporlanır. `close()` yeni kabulü durdurur, beklemez; daemon işçisi süreç yaşadığı sürece mevcut kuyruğu boşaltabilir. İş çıkışında teslim garantili flush bulunmaz. Varsayılan ortak üst sınır 64 MiB/1024 kayıttır. Bekleyen kodlanmış paket, özgün görüntü ve kodlama geçici kopyaları aynı konservatif bütçeye ayrılır. Bir stream tamamlanmadan kapanmışsa veya gözlem bütçesi dolmuşsa terminal kaydı `complete=false` taşır; gövde sessizce kesilip tamamlanmış sayılmaz. ## Teknik doğrulama Kaynak testleri: `python -m pytest sdk/python/tests`. `consumer/conformance.py CONFIG OUTPUT [INCOMING_CARRIER]` yalnız test tüketicisidir; kuruma kurdurulan bir servis veya başlangıç yardımcısı değildir. Paketin kendisi kaynak depoya veya test vektörü dosyalarına bağımlı değildir.