SDK entegrasyonları

Python · Belge asistanı

FastAPI/ASGI üzerinde retrieval, model girdisi, çıktı ve kaynak bilgisini izleyin.

Finans 0.44.0SDK 0.11.026 Ekim 2026

Örnek projeyi indirSentetik senaryo · kaynak kod ve kurulum adımları

#1. Wheel paketini yükleyin

Python 3.10+ kullanın. Portalın servis için verdiği wheel’i kurumunuzun izin verdiği ortamda yükleyin.

python -m pip install ./packages/sigillum_finans_sdk-0.11.0-py3-none-any.whl
python -m pip install fastapi uvicorn

HTTPX, OpenTelemetry ve cryptography SDK bağımlılıklarıdır; kurumun paket aynası üzerinden çözümlenebilir.

app.py

"""Deterministik doküman araması; gerçek LLM çağrısı değildir."""
import json
import os
from pathlib import Path
from fastapi import FastAPI
from pydantic import BaseModel, Field
from sigillum_finans import start, JsonData, Attachment, References

sdk = start(Path(os.environ["SIGILLUM_CONFIG"]).resolve())
api = FastAPI(title="Sigillum SDK · Doküman asistanı demosu")
DOCUMENTS = (
    ("D01", "Kart başvurusu mobil uygulama üzerinden yapılır."),
    ("D02", "Adres değişikliği müşteri profili ekranından yapılır."),
    ("D03", "Havale işlemi para transferi menüsünden yapılır."),
)
def data(value):
    return JsonData.raw(json.dumps(value, ensure_ascii=False, separators=(",", ":")))

class Query(BaseModel):
    request_ref: str = Field(min_length=1, max_length=64)
    question: str = Field(min_length=1, max_length=500)

@api.post("/assist")
async def assist(query: Query):
    sdk.set_references(References(session_ref=query.request_ref))
    with sdk.start_step("document-retrieval") as step:
        words = set(query.question.casefold().split())
        ranked = sorted(DOCUMENTS,
            key=lambda item: len(words & set(item[1].casefold().split())), reverse=True)
        chosen = ranked[0]
        step.observe("ai", "retrieval", data({
            "method": "synthetic-keyword-overlap",
            "query": query.question, "documents": [{"id": chosen[0], "text": chosen[1]}]
        }))
    with sdk.start_step("answer-compose") as step:
        result = {"request_ref": query.request_ref, "answer": chosen[1],
                  "source": chosen[0], "demonstration": True}
        step.observe("ai", "explanation", data({
            "method": "document-quotation", "source": chosen[0],
            "message": "En yüksek kelime örtüşmesine sahip demo metni seçildi."
        }))
        step.observe("custom", "assistant.result", data(result))
        original = json.dumps(result, ensure_ascii=False).encode("utf-8")
        step.observe("source", "comparison.source", data({"reference": query.request_ref}),
            attachments=(Attachment("result", original, "application/json",
                                    "comparison.originalContent"),))
    return result

@api.get("/sdk-status")
def status():
    return {"ready": sdk.status.state == "ready", "pending_records": sdk.status.pending_records,
            "lost": sdk.status.lost}

app = sdk.wrap_asgi(api)

Kurum portalınızdan alınan yapılandırmayla kullanın.

#2. ASGI uygulamasını sarın

start(Path(...).resolve()) ile tek SDK nesnesi oluşturun. Route’ları tanımladıktan sonra app = sdk.wrap_asgi(api) kullanın. SDK standart ASGI HTTP mesaj sınırını ve kapsam içindeki HTTPX çağrılarını gözler. WebSocket, keyfi socket veya bütün Python kütüphaneleri için otomatik yakalama iddiası yoktur.

#3. Belge asistanı senaryosu

Demo POST /assist isteğinde kısa bir soru alır. Üç yerel sentetik belgeden basit kelime eşleşmesiyle kaynak seçer; deterministik bir örnek cevap üretir. Gerçek LLM değildir. Retrieval kaynak içeriği, açıklama, iş sonucu ve kaynak eki ayrı gözlemler olarak eklenir.

#4. JSON, ekler ve referanslar

JsonData.raw geçerli bir JSON nesnesini str veya değişmez bytes olarak alır. Attachment özgün içeriği taşır. References ve ExternalReference kişi/oturum/iş referanslarını ekler. JSON içindeki büyük sayıları gözlem için gereksiz parse/serialize döngüsünden geçirmeyin.

#5. Gerçek model çağrısına geçiş

sdk.call_ai ve call_ai_async gerçek çağrıyı bir kez çalıştırır. Çıktı ham JSON değilse output= seçicisi özgün JSON’u verir. Stream’i örnek almak için önceden tüketmeyin; gerçek tüketim sırasında gözlem üretin.

#6. Örneği çalıştırın

ZIP içindeki README’ye göre .sigillum/config.json dosyasını yerleştirin. uvicorn app:app --host 127.0.0.1 --port 5110 ile başlatın. Portal başlangıcı POST /assist olmalı. /sdk-status yanıtını gözlem kanıtı yerine kullanmayın; gerçek /assist isteği gönderin.

Sigillum Finans · Güncel kaynak sözleşmesi