Maliyet & fiyatlandırma gözlemlenebilirliği

GNL, model çağrılarının usage bilgisini (input/output/cached token) journal'a yazar. getRunCost bu journal'ı POST-HOC tarayarak run başına tam ve deterministik bir maliyet hesabı çıkarır — canlı/tahmini bir "cost guard" değil, gerçekten olan biteni birebir toplar. Bir run bittikten sonra "bu konuşma bana kaça mal oldu, hangi model ne kadar tüketti" sorusuna cevap gerektiğinde, fatura/kullanım raporu üretirken ya da OTel uyumlu bir gözlemlenebilirlik zincirine (trace exporter) beslemek istediğinizde kullanılır.

Ayrı bir alt-paket gerekmez; @gnldev/durable kök export'undan gelir.

import { getRunCost, toTraceSpans } from '@gnldev/durable';

getRunCost, bir JournalReader ve runId alır; run'daki tüm model girdilerinin usage'ını toplar, fiyat tablosundan (varsayılan DEFAULT_PRICING) maliyeti hesaplar:

const cost = await getRunCost(reader, runId);
// { runId, inputTokens, outputTokens, cachedTokens, totalTokens,
//   modelCalls, toolCalls, costUsd, byModel: { 'claude-sonnet-5': { calls, tokens, costUsd }, ... } }

Kendi fiyat tablonuzu geçmek isterseniz opts.pricing ile override edebilirsiniz; journal'da model id'si yoksa (mock model vb.) opts.modelId ile varsayılan atarsınız:

const cost = await getRunCost(reader, runId, { modelId: 'claude-sonnet-5' });

Bir OTel exporter'a beslemek veya waterfall görselleştirmesi için journal'ı gen_ai.* semantik-uyumlu span listesine çevirin:

const spans = await toTraceSpans(reader, runId);
// [{ name: 'llm.generate' | 'tool.execute', kind: 'model' | 'tool', runId, seq, attributes }, ...]

Fiyat tablosunu deploy gerektirmeden güncellemek isterseniz journal'daki __pricing__ dokümanını okuyup etkin tabloyu alabilirsiniz (journal'da kayıt yoksa DEFAULT_PRICING'e düşer):

import { effectivePricingTable } from '@gnldev/durable';
const table = await effectivePricingTable(journal); // __pricing__ (varsa) > DEFAULT_PRICING

Studio, aynı hesaplamayı REST üzerinden sunar — kendi backend'inizde tekrar implemente etmeniz gerekmez:

GET /runs/:id/cost   → getRunCost(reader, id)
GET /runs/:id/trace  → journal'dan waterfall span'leri (maliyet dahil)