Python SDK tam başvuru

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.

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.

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:

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 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:

"localTransfer": {
  "endpoint": "http://127.0.0.1:29520",
  "token": "PRODUCT_INSTALLER_GENERATES_A_LOCAL_TOKEN"
}

Yerel adres yalnız http://127.0.0.1:<port> 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.

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.

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:

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.

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.

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.

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.