3. Teori: Constrained Decoding dan @Generable Internals

Bagaimana @Generable Bekerja di Tingkat Bawah

Ketika Anda menulis @Generable, macro Swift menghasilkan conformance ke protokol Generable. Di runtime, framework menggunakan informasi ini untuk membangun JSON Schema yang dikirim bersama prompt:

swift
@Generable struct ProductInfo {     Macro menghasilkan schema:
    var name: String           →    {
    var price: Double          →      "type": "object",
    var inStock: Bool          →      "properties": {
}                              →        "name": {"type": "string"},
                               →        "price": {"type": "number"},
                               →        "inStock": {"type": "boolean"}
                               →      },
                               →      "required": ["name", "price", "inStock"]
                               →    }

Schema ini dikirim ke model bersama prompt. Model kemudian menghasilkan token dengan constrained decoding — pada setiap langkah, hanya token yang valid secara JSON Schema yang diizinkan. Hasilnya dijamin sesuai struktur.

Mengapa Enum Lebih Efisien dari String

swift
// ❌ Tidak optimal: model harus "menebak" string yang tepat
@Generable
struct Analysis {
    @Guide(description: "Kategori: technology, finance, health, entertainment, sports, atau other")
    var category: String  // Model bisa menghasilkan nilai yang tidak terduga
}

// ✓ Optimal: constrained ke nilai yang valid — lebih cepat dan lebih akurat
@Generable
enum Category: String {
    case technology, finance, health, entertainment, sports, other
}

@Generable
struct Analysis {
    @Guide(description: "Kategori konten")
    var category: Category  // Hanya token yang valid secara enum yang dihasilkan
}

Enum mengurangi token search space secara drastis. Model tidak perlu menghasilkan karakter demi karakter untuk string arbitrer — hanya memilih dari set terbatas yang sudah diketahui.

@Guide dan Kualitas Output

@Guide bukan sekadar dokumentasi — ia secara langsung mempengaruhi kualitas output karena dikirim ke model sebagai bagian dari schema description:

swift
// ❌ @Guide yang buruk: terlalu umum, tidak memberikan constraint yang jelas
@Generable
struct UserProfile {
    @Guide(description: "Nama")
    var name: String

    @Guide(description: "Umur")
    var age: Int
}

// ✓ @Guide yang baik: spesifik, memberikan constraint dan format yang jelas
@Generable
struct UserProfile {
    @Guide(description: "Nama lengkap pengguna, huruf kapital di awal setiap kata")
    var name: String

    @Guide(description: "Umur dalam tahun, antara 0 sampai 120")
    var age: Int

    @Guide(description: "Kode negara ISO 3166-1 alpha-2 dua huruf, contoh: ID, US, JP")
    var countryCode: String

    @Guide(description: "Daftar minat maksimal 5 item, lowercase, tanpa spasi (gunakan dash), contoh: machine-learning, ios-dev")
    var interests: [String]
}