Model adaptörleri

Uyumluluk: Pactmark 0.2.x. @pactmark/ai-sdk, Vercel AI SDK entegrasyonunu isteğe bağlı bir peer bağımlılık olarak gösterir; tipleri asla çekirdek API’lere girmez.

Bir adaptör neyden sorumludur

Bir model adaptörü beş şeyi normalize eder, başka bir şey yapmaz:

Akış hâlindeki içerik

Sağlayıcı parçaları, çalışma zamanının sınır zorlayabileceği sınırlı ve sayılabilir bir akışa dönüşür.

Araç talepleri

Sağlayıcının araç-çağrısı biçimleri, bir kayıt özetine atıfta bulunan tool_call’a dönüşür.

Bitiş nedenleri

“Bitti” ile “token’ı tükendi”yi ayırt edebilmek için normalize edilir.

Kullanım muhasebesi

Girdi ve çıktı kullanımı, hesaplanamadığında açık bir başarısızlıkla.

Yeniden deneme sınıflandırması

timed_out, retryable veya uncertain — üçüncüsü ikincisinin eşanlamlısı değildir.

Başka hiçbir şey

Bir adaptör politika belirlemez, başka çağrılar için kimlik bilgisi çözmez ve olay yazmaz.

Beyan etmek zorunda olduğunuz iki profil

const security = defineModelSecurityProfile({
  id: "billing.assistant.model@1",
  provider: "anthropic",
  model: "claude-sonnet-5",
  endpointOrigin: "https://api.anthropic.com",
  credentialSlot: "anthropic.primary",
  allowedTenants: ["acme"],
  allowedPurposes: ["service_delivery"],
  allowedDataClasses: ["internal", "confidential"],
  processingRegion: "us",
  retention: "none",
  logging: "none",
  training: "none",
  contractReference: "MSA-2026-114 §7",
});

Bu alanların her biri, sağlayıcı sözleşmeniz hakkında yaptığınız bir iddiadır. Hepsi modelSecurityProfileDigest’in parçası olur ve o da kabul edilmiş iş emriyle taşınır — böylece bölge, saklama veya eğitim duruşundaki bir değişiklik sessiz değil görünür bir kimlik değişikliği olur.

const resources = defineModelResourceProfile({
  id: "billing.assistant.resources@1",
  implementationVersion: "1.0.0",
  maxInputBytesPerCall: 200_000,
  maxInputTokensPerCall: 60_000,
  maxOutputTokensPerCall: 4_000,
  maxStreamedOutputBytesPerCall: 200_000,
  maxStreamEventsPerCall: 4_000,
  maxToolResultToContextBytes: 32_000,
  maxContextSnapshotBytes: 400_000,
  maxRunModelInputBytes: 2_000_000,
  maxRunModelInputTokens: 400_000,
  maxRunModelOutputBytes: 400_000,
  maxRunModelOutputTokens: 40_000,
  maxRunToolResultToContextBytes: 200_000,
  estimator: "tokenizer.approx@1",
  providerOutputCap: "enforced",
});

providerOutputCap: "enforced", sağlayıcının çıktıyı kendisinin sınırlayacağını iddia eder. Sağlayıcınız bunu yapamıyorsa öyle söyleyin — desteklenmeyen bir çıktı tavanı veya kullanılamaz kullanım muhasebesi, fatura geldiğinde keşfedilmek yerine dışa aktarımdan önce başarısız olur.

Kimlik bilgileri

Şekil 1. Çalışma zamanı önce kötümser bir model-çağrısı rezervasyonu alır, sonra o çağrıya bağlı kısa ömürlü bir ModelCredentialRef verir. Adaptör onu çözer, başka hiçbir şeyi çözmez.

async function invoke(request, { credentialRef }) {
  const apiKey = await resolveModelCredential(credentialRef); // yalnızca bu çağrıya bağlı
  // …hemen kullanın, asla saklamayın, asla loglamayın
}

Ham prompt’lar, tamamlamalar ve gizli akıl yürütme olağan telemetri ve kanıtın dışında kalır. Adaptörünüz varsayılan olarak istekleri loglayan bir istemciyi sarmalıyorsa bunu kapatın — redaksiyon kanaryaları CI’da yakalar, ama yakalamak zorunda kalmamalı.

Yeniden deneme sınıflandırması bir güvenlik kararıdır

function classify(error) {
  if (error.name === "AbortError") return "timed_out";
  if (error.status === 429 || error.status >= 500) return "retryable";
  if (responseWasLostAfterSend(error)) return "uncertain";
  throw error;
}

Bunu yanlış yapmak her iki yönde de pahalıdır. Belirsiz bir sonucu retryable saymak işi tekrarlatır; yeniden denenebilir bir sonucu uncertain saymak ilerleyebilecek koşuları park eder.

Belirsiz biten bir model çağrısı, rezervasyonda maksimum ücretini korur. Bu kasıtlıdır: alternatifi, bütçe sızdıran bir çökme döngüsüdür.

Testler için deterministik modeller

Ajan davranışını test etmek için sağlayıcı anahtarına ihtiyacınız yok ve CI’da istememelisiniz:

import { FakeModelDriver } from "@pactmark/testing";

const driver = new FakeModelDriver({
  turns: [
    { type: "tool_call", value: { /* … */ } },
    { type: "final", value: { summary: "…" } },
  ],
});

Deterministik sürücü gerekli davranışı — sıralama, sınırlar, araç bağlama, bitiş nedenleri — canlı bir sağlayıcı olmadan kapsar. Depodaki her örnek böyle çalışır.

Kayıt ve sapma

Bir model adaptörü kaydı; sağlayıcıyı, model fabrikasını, güvenlik ve kaynak profillerini, uç noktayı, uygulama sürümünü ve kaynak özetini bağlar. Herhangi birini değiştirmek özeti değiştirir ve eskisine göre kabul edilmiş bir koşu yenisiyle sessizce devam etmez — KAF_MODEL_ADAPTER_MISMATCH.

Gözlemlenebilirlik ve gizlilik

Bir model çağrısı hakkında ne kaydedilebilir, ne kaydedilemez.

Ajan testi

Sahte bir sürücü etrafında deterministik senaryolar kurmak.

Başlarken

Temel kavramlar

Rehberler

Dağıtım

Üretim

Güvenlik

Model adaptörleri

Bir adaptör neyden sorumludur

Akış hâlindeki içerik

Araç talepleri

Bitiş nedenleri

Kullanım muhasebesi

Yeniden deneme sınıflandırması

Başka hiçbir şey

Beyan etmek zorunda olduğunuz iki profil

Kimlik bilgileri

Yeniden deneme sınıflandırması bir güvenlik kararıdır

Testler için deterministik modeller

Kayıt ve sapma

Gözlemlenebilirlik ve gizlilik

Ajan testi

​Bir adaptör neyden sorumludur

Akış hâlindeki içerik

Araç talepleri

Bitiş nedenleri

Kullanım muhasebesi

Yeniden deneme sınıflandırması

Başka hiçbir şey

​Beyan etmek zorunda olduğunuz iki profil

​Kimlik bilgileri

​Yeniden deneme sınıflandırması bir güvenlik kararıdır

​Testler için deterministik modeller

​Kayıt ve sapma

Gözlemlenebilirlik ve gizlilik

Ajan testi

Bir adaptör neyden sorumludur

Beyan etmek zorunda olduğunuz iki profil

Kimlik bilgileri

Yeniden deneme sınıflandırması bir güvenlik kararıdır

Testler için deterministik modeller

Kayıt ve sapma