Prompt Programming dengan Guidance

Dua berkas di akar repository, 12_guidance_roles.py dan 12_guidance_syntax.py, memakai pustaka Guidance untuk menulis prompt sebagai program Python, bukan sebagai satu string panjang. Keduanya menyusun objek lm selangkah demi langkah: satu blok with menambah satu giliran percakapan, lalu satu panggilan gen(...) menambah satu slot teks yang bisa dibaca kembali lewat namanya. Di README, topik ini tercatat sebagai bagian ke-12 dengan durasi video 43:15 (README.md:30¹).

Dua berkas, satu pola

Keduanya lahir dari satu peristiwa yang sama, yaitu migrasi dari Guidance 0.x ke 1.x. Berkas roles dibuka dengan catatan bahwa kode aslinya memakai template gaya Handlebars seperti {{#system}} dan {{gen}}, lalu diganti decorator dan function-based API (12_guidance_roles.py:1-6²). Berkas syntax menambahkan bahwa fitur lanjutan seperti {{#geneach}} dan {{select}} diganti loop Python, dan sebagian fitur disederhanakan karena perubahan API (12_guidance_syntax.py:1-7³).

Perbedaan keduanya terletak pada role context yang dipakai dan batas max_tokens tiap slot keluaran:

Hanya berkas roles yang memakai system. Berkas syntax mengimpor models, gen, user, dan assistant saja, lalu menaruh seluruh teks literal di dalam blok role — komentarnya menyebut "all text must be within role contexts" (12_guidance_syntax.py:9-18⁴, 12_guidance_syntax.py:30-41⁵).

Model dan role context

Kedua berkas menginisialisasi model dengan satu baris yang identik bentuknya: models.OpenAI("gpt-3.5-turbo"). Pada berkas roles, baris itu didahului load_dotenv() dan diikuti variabel os_name = "Linux" yang masuk ke dalam f-string prompt (12_guidance_roles.py:8-14⁶). Pada berkas syntax, komentar di baris yang sama mencatat bahwa model ini menggantikan text-davinci-003 (12_guidance_syntax.py:9-18⁴).

Hal yang mudah terlewat: giliran pertama memakai lm = llm + ..., sedangkan giliran berikutnya memakai lm += .... Objek lm hanya dinamai sekali, lalu ditambahi terus (12_guidance_roles.py:20-27⁷).

Siklus percakapan multi-giliran

Berkas roles membangun percakapan dua giliran jawaban. Giliran pertama meminta daftar perintah Linux beserta deskripsi satu baris; giliran kedua menanyakan perintah mana yang paling sering salah dipakai pemula, dengan max_tokens sama besarnya, yaitu 100 (12_guidance_roles.py:20-27⁷, 12_guidance_roles.py:29-38⁸).

sequenceDiagram
  participant S as 12_guidance_roles.py
  participant L as lm
  participant M as models.OpenAI "gpt-3.5-turbo"
  S->>L: blok system menambah persona CS Professor
  S->>L: blok user menambah permintaan daftar perintah Linux
  S->>L: blok assistant dibuka
  S->>M: gen("commands", max_tokens=100)
  M-->>L: slot commands terisi
  S->>L: blok user menambah pertanyaan perintah yang membingungkan
  S->>L: blok assistant dibuka
  S->>M: gen("confusing_commands", max_tokens=100)
  M-->>L: slot confusing_commands terisi
  L-->>S: lm["commands"] dan lm["confusing_commands"]
%% fig: Giliran percakapan pada berkas roles
%% desc: Setiap blok role menambah teks ke objek lm, dan setiap gen menambahkan satu slot keluaran yang dinamai, sehingga percakapan terbangun bertahap sebelum dibaca.

Nilai acak yang disuntikkan ke giliran user

Berkas syntax menunjukkan bagian yang tidak bisa dilakukan template statis: dua nilai acak dihitung lebih dulu di Python, lalu dimasukkan ke f-string giliran user (12_guidance_syntax.py:20-28⁹, 12_guidance_syntax.py:30-41⁵).

graph LR
  Q["quizflavor: 4 variasi"] --> C["random.choice"]
  C --> F["flavor"]
  R["random.randint(1, 5)"] --> P["randomPts"]
  A["gen commands_list max_tokens 300"] --> U["giliran user: f-string kuis"]
  F --> U
  P --> U
  U --> G["gen quiz_explanation max_tokens 200"]
  style Q fill:#f59e0b,color:#000
  style R fill:#f59e0b,color:#000
  style C fill:#f59e0b,color:#000
  style F fill:#8b5cf6,color:#fff
  style P fill:#8b5cf6,color:#fff
  style U fill:#2d7d46,color:#fff
  style A fill:#336791,color:#fff
  style G fill:#336791,color:#fff
%% fig: Suntikan nilai acak ke giliran user
%% desc: random.choice dan random.randint menghasilkan flavor serta randomPts, keduanya masuk ke f-string kuis yang juga merujuk daftar perintah dari slot commands_list.

Giliran kedua berkas syntax juga memuat instruksi "pick 3 from the list above", sehingga prompt bergantung pada isi slot commands_list yang dihasilkan giliran sebelumnya (12_guidance_syntax.py:30-41⁵).

Membaca slot hasil

Hasil tidak diambil dari objek response, tetapi dari lm dengan nama slot sebagai kunci. Berkas roles mencetak lm["commands"], pemisah "===", lalu lm["confusing_commands"] (12_guidance_roles.py:29-38⁸). Berkas syntax melakukan pola yang sama dengan label tambahan sebelum tiap slot (12_guidance_syntax.py:44-48¹⁰).

Konsekuensinya, nama slot menjadi semacam schema keluaran: gen pertama hanya mengisi commands_list, gen kedua mengisi quiz_explanation, dan keduanya tetap terpisah walau berada di objek yang sama.

Jebakan versi

⚠️ requirements.txt masih mengunci guidance==0.3.1 (requirements.txt:44¹¹), sedangkan kedua berkas menyatakan diri sudah dimigrasi ke 1.x dan mengimpor models, gen, serta blok role dari guidance (12_guidance_roles.py:1-6², 12_guidance_roles.py:8-14⁶, 12_guidance_syntax.py:1-7³). Jika dependensi dipasang apa adanya dari berkas itu, versi yang terpasang tidak sesuai dengan API yang dipanggil kode. Periksa versi terpasang sebelum menjalankan kedua skrip ini.

Untuk pola percakapan yang berjalan lama dan perlu menghemat panggilan model, lihat Caching dan Aplikasi Chat Streamlit.