IO & Multimodal

Proje kökü ve @ yolları

proje/                     ← io kökü (en yakın package.json burada)
├── package.json
├── luma/
│   └── fatura.luma        çalıştırılan program
├── 0213/
│   ├── page-1.png
│   └── page-2.png
└── docs/
    └── belge.md

  "@0213/page-1.png"  →  proje/0213/page-1.png
  "@/docs/belge.md"   →  proje/docs/belge.md
  "docs/belge.md"     →  proje/docs/belge.md   (@ olmadan da kök-göreli)
  "../gizli"          →  reddedilir

Dosya okuma ve yazma

import io from "std/io"

agent FileWorker {
  fn run() -> Result {
    exists  = io.exists("@docs/belge.md")
    text    = io.readText("@docs/belge.md")
    mime    = io.mimeType("@0213/page-1.png")     // "image/png"
    file    = io.readFile("@0213/page-1.png")
    dataUrl = io.toDataUrl(file)
    written = io.writeText("@cikti/ozet.md", text)
    return { path: written }
  }
}

io.readFile sonucunun şekli

{
  "path":      "0213/page-1.png",
  "mime_type": "image/png",
  "base64":    "iVBORw0KGgoAAAANSUhEUg…",
  "size":      184213
}

MIME eşlemesi

io.writeText hedefin ara klasörlerini otomatik oluşturur — çıktı klasörünü önceden hazırlamana gerek yoktur.

Dosya listeleme

pages = io.listFiles("@0213", "*.png", false)
// ["@0213/page-1.png", "@0213/page-2.png", "@0213/page-10.png"]

pages = io.listFiles("@0213", "*.png", false)
for page in pages {
  ...
}

// The pattern cannot contain a path:
pages = io.listFiles("@", "0213/*.png", false)
// io listFiles pattern expects
// only a file name glob.

Multimodal marker'lar

Görsel ve dosya içeriği prompt'a marker olarak gömülür. Model profilinde multimodal: true olduğunda bu marker'lar content part'larına çevrilir.

{{image_url:<url veya data URL>}}
{{file_url:<url veya data URL>}}

// 1) A single file, by hand
file    = io.readFile("@0157.pdf")
dataUrl = io.toDataUrl(file)
text    = ask "Bu faturayı Markdown'a çevir. Belge: {{file_url:{dataUrl}}}" -> Transcript

// 2) Many files, automatically
files   = io.readFiles(pages)
markers = io.toMultimodalMarkers(files)
text    = ask "Tüm sayfaları sırayla Markdown'a çevir: {markers}" -> Transcript

Bu iki biçim birbirinin yerine geçmez ve ikisini ayıran kural bellekle ilgilidir. io.readFiles kendisine verdiğin her yolu okur, her birini base64'e çevirir ve listenin tamamını döndürür — yani dosyaların hepsi aynı anda bellekte durur, diskteki boyutlarının kabaca 4/3'ü kadar. Dosyalar küçükse ve zaten hepsini tek prompt'ta istiyorsan liste ver; sayfa, tarama veya PDF söz konusuysa her seferinde [tek] ver. Aşağıdaki uçtan uca pipeline'ın bir kez io.readFiles(pages) yerine döngü içinde io.readFiles([page]) çağırmasının nedeni budur.

Error: Result set exceeded the row limit (200000). Process in batches with col.chunk, or raise --max-rows.

io.toMultimodalMarkers her dosyanın MIME tipine bakarak doğru marker'ı seçer ve satır satır birleştirir:

Provider content eşlemesi

Uçtan uca: çok sayfalı fatura çıkarımı

Aşağıdaki pipeline, bir klasördeki PNG sayfalarını okuyup Markdown'a çevirir, sonra bu Markdown'dan tipli fatura verisi çıkarır ve iki dosya yazar. Depodaki luma/064_invoice_multi_desc_prompt.luma örneğinin özüdür.

  @0213/*.png  (doğal sırayla)
       ↓  her sayfa için ayrı multimodal ask
  Markdown parçaları  →  birleştir  →  @0213/pre.md
       ↓  schema.prompt(InvoiceExtract) + Markdown
  InvoiceExtract  (typed, doğrulanmış)
       ↓
  @0213/ext.json

1. Girdi ve modelleri tanımla. Görsel için multimodal, metin çıkarımı için geniş bağlamlı ayrı bir model kullanmak hem kaliteyi hem maliyeti iyileştirir.
   luma

   input folder: string
   
   import io     from "std/io"
   import json   from "std/json"
   import schema from "std/schema"
   import num    from "std/numeric"
   
   model Vision {
     provider: "openai-compatible"
     base_url: "https://gateway.example/v1"
     model: "vision-model"
     api_key: getEnv("api_key")
     max_tokens: 6000
     multimodal: true
   }
   
   model TextExtractor {
     provider: "openai-compatible"
     base_url: "https://gateway.example/v1"
     model: "text-model"
     api_key: getEnv("api_key")
     max_tokens: 24000
   }

2. Çıktı schema'sını alan açıklamalarıyla birlikte yaz. @desc metinleri JSON Schema'ya girer ve model için extraction talimatı işlevi görür.
   luma

   schema InvoiceItem {
     line_no: int | null   @desc("Faturadaki kalem sıra numarası")
     description: string | null @desc("Mal veya hizmet açıklaması")
     quantity: float | null @desc("Satılan miktar")
     unit_price: float | null @desc("İndirim öncesi birim fiyat")
     total: float | null @desc("Kalemin indirim sonrası KDV hariç toplamı")
   
     where quantity == null || unit_price == null || total == null || num.approximatelyEqual(quantity * unit_price, total, 0.01)
       @feedback("quantity * unit_price toplamına uymuyor")
   }
   
   schema MetaEntry {
     key: string
     value: string
   }
   
   schema InvoiceExtract
     @desc("Fatura Markdown'ından çıkarılan yapılandırılmış veri")
     @prompt("Aşağıdaki fatura Markdown metninden InvoiceExtract schema'sına uygun JSON üret. Alan açıklamalarını extraction talimatı olarak kullan. Her tabloda görünen her kalem için items içinde ayrı bir nesne üret; satır atlama veya özetleme. Metinde bulunmayan değerleri uydurma; nullable alanlarda null, array alanlarda [] kullan. Schema alanlarına sığmayan hiçbir bilgiyi kaybetme; bunları meta alanında anahtar-değer olarak koru.") {
     invoice_number: string | null @desc("Fatura numarası")
     invoice_date: string | null @desc("Fatura tarihi, YYYY-MM-dd HH:mm")
     items: InvoiceItem[] @desc("Faturadaki tüm kalemler")
     notes: string[]      @desc("Dipnotlar ve banka bilgileri")
     meta: MetaEntry[]   @desc("Schema alanlarına girmeyen tüm bilgiler")
   }

3. Sayfaları tek tek transkribe et. Her sayfayı ayrı bir ask ile işlemek, tek istekte tüm sayfaları göndermekten belirgin şekilde daha güvenilirdir: token limiti aşılmaz ve model sayfaları karıştırmaz.
   luma

   agent InvoiceReader {
     model: Vision
     retry: 2
   
     fn transcribe() -> InvoiceTranscript {
       root     = "@" + folder
       pages    = io.listFiles(root, "*.png", false)
       markdown = ""
   
       for page in pages {
         files   = io.readFiles([page])
         markers = io.toMultimodalMarkers(files)
         part    = ask "Bu fatura görselini eksiksiz Markdown'a çevir. Tabloyu Markdown tablosu olarak koru; şirket, müşteri, kalemler, KDV, toplamlar ve dipnotları aktar. Yalnızca markdown alanını doldur. Görsel: {markers}" -> InvoiceTranscript
         markdown = markdown + part.markdown + "\n\n"
       }
   
       written = io.writeText(root + "/pre.md", markdown)
       return { markdown: markdown }
     }
   }

4. Markdown'dan tipli veriyi çıkar. Talimat schema'nın kendisinden okunur.
   luma

   agent InvoiceExtractor {
     model: TextExtractor
     retry: 2
   
     fn extract(markdown: string) -> InvoiceExtract {
       instruction = schema.prompt(InvoiceExtract)
       result  = ask "{instruction}\n\nFATURA MARKDOWN:\n\n{markdown}" -> InvoiceExtract
       root    = "@" + folder
       written = io.writeText(root + "/ext.json", json.pretty(result))
       return result
     }
   }

5. Pipeline'ı bağla ve çalıştır.
   luma

   reader     = InvoiceReader()
   extractor  = InvoiceExtractor()
   transcript = reader.transcribe()
   result     = extractor.extract(transcript.markdown)

   bun src/index.ts luma/fatura.luma \
     --folder 0213 \
     --all \
     --trace-file /tmp/fatura-trace.json

Neden bu şekilde?

jq -r '.events[] | select(.type=="validation" and .ok==false)
        | "\(.name) [\(.metadata.rule // "-")] \(.error // "-")"' /tmp/fatura-trace.json