---
name: jev
description: Pasangkan Jev (TypeSafe System One) sebagai partner keputusan untuk keputusan terstruktur yang berulang - routing, scoring, approval, escalation, klasifikasi, guardrail. Pakai skill ini setiap kali ada pilihan dari daftar tertutup, penilaian terhadap rubrik, pengecekan benar/salah terhadap dokumen, atau saat menulis kode yang memakai typesafe-sdk. Cocok untuk mengganti prompt "kembalikan JSON" yang rapuh dengan jawaban bertipe.
license: MIT
metadata:
  version: "1.0.0"
  repository: "https://github.com/devnolife/copilot-jev"
---

# Jev sebagai Partner Keputusan

## Pembagian peran

Jev bekerja **berpasangan** dengan kamu, bukan menggantikanmu:

```
LLM (kamu)  ->  riset, perencanaan, penulisan, penulisan kode
Jev         ->  routing, scoring, approval, escalation
Kode        ->  mengeksekusi keputusan
```

Kamu yang memahami maksud dan menyusun rencana. Jev yang menjawab "mana yang
dipilih, seberapa yakin, apakah sudah cukup" — dengan angka, dalam milidetik,
dengan biaya nyaris nol.

Jev **tidak** menulis teks, **tidak** membuat kode, dan **tidak** menjelaskan
alasannya. Ia menerima `state` + pertanyaan bertipe, lalu mengembalikan jawaban
bertipe beserta probabilitas. Jangan pernah memintanya melakukan hal lain —
itu bagianmu.

Karena keduanya partner dan bukan substitusi, tidak ada setelan
`model: jev-latest` yang mengubah coding agent menjadi agent berbasis Jev.

## Kapan memakai Jev

Pakai kalau keputusannya:

- memilih satu dari daftar opsi tertutup (routing, klasifikasi, function calling)
- menilai sesuatu terhadap rubrik (urgensi, kualitas, risiko, relevansi)
- memeriksa apakah sebuah pernyataan benar atas dokumen/record (guardrail, verifikasi)
- berulang, sehingga biaya dan latency LLM jadi terasa

Jangan pakai kalau hasilnya harus berupa prosa, kode, ringkasan, atau daftar
terbuka.

## Tiga primitive

| Tipe | Untuk | `criteria` | Balikan |
|---|---|---|---|
| `choice` | pilih 1 dari N (maks 255) | map opsi → deskripsi (**wajib**) | `choice`, `probabilities`, `confidence` |
| `score` | nilai terhadap 2–10 level | array terurut (**wajib**) | `score`, `legend`, `probabilities`, `confidence` |
| `noul` | pernyataan ya/tidak | opsional `{true, false}` | `noul` 0..1 — **tanpa `confidence`** |

> **Jebakan paling sering:** Noul tidak mengembalikan `confidence`. Turunkan
> kepastiannya sendiri: `certainty = abs(noul - 0.5) * 2`. Nilai 0.5 berarti
> benar-benar ragu; 0.03 sama tegasnya dengan 0.97.

Detail lengkap tiap tipe: [reference/primitives.md](reference/primitives.md).

## Aturan yang wajib diikuti

1. **Satu panggilan, banyak pertanyaan.** Jev membaca `state` sekali lalu
   menilai semua pertanyaan paralel. Gabungkan. Memanggil API sekali per
   pertanyaan membuang uang dan waktu.
2. **Kirim bukti, bukan ringkasan.** `"researcher sudah selesai"` tidak bisa
   dinilai. Kirim isi sumbernya, isi draftnya, jumlahnya.
3. **Refresh opsi secara dinamis.** Kirim hanya opsi yang benar-benar mungkin
   saat ini. Opsi mati menyerap probabilitas dan menurunkan confidence percuma.
4. **Kalau opsi tinggal satu, jangan panggil Jev.** Itu keputusan deterministik.
5. **Gerbangi sesuai risiko.** Ambang bukan satu angka untuk seluruh sistem.
   Aksi yang mahal kalau salah butuh ambang lebih tinggi.
6. **Pisahkan "DONE" dari verifikasi outcome.** Model bilang selesai tidak sama
   dengan artefaknya benar-benar ada dan valid. Verifikasi di kode.
7. **Taruh semua pertanyaan dan ambang di satu file.** Itu bagian yang paling
   perlu direview manusia; jangan disebar.
8. **Ukur.** Tanpa angka biaya dan latency, klaim penghematan hanya tebakan.

Pola arsitekturalnya: [reference/patterns.md](reference/patterns.md).

## Bentuk request

```http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY
Content-Type: application/json
```

```json
{
  "state": "<bukti: isi dokumen, pesan, atau state agent>",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Tim mana yang harus menangani ini?",
      "criteria": {
        "billing": "Pembayaran, invoice, refund",
        "technical": "Bug, outage, integrasi",
        "sales": "Harga, upgrade, akun baru"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "Seberapa mendesak pesan ini?",
      "criteria": ["Tidak mendesak", "Cukup mendesak", "Sangat mendesak"]
    },
    "needs_human": {
      "type": "noul",
      "instructions": "Kasus ini perlu ditangani manusia, bukan otomasi."
    }
  }
}
```

Tiga pertanyaan, satu panggilan. Jawaban kembali di bawah kunci yang sama.

## Python

```bash
pip install typesafe-sdk      # BUKAN `typesafe`. Butuh Python >= 3.10.
```

```python
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()                     # baca TYPESAFE_API_KEY dari env
result = client.system_one(state, questions)  # SATU panggilan untuk semua

result.choices["department"].choice        # "billing"
result.choices["department"].confidence    # 0.81
result.choices["department"].probabilities # {"billing": 0.88, ...}
result.scores["urgency"].score             # 1.4
result.nouls["needs_human"].noul           # 0.95  (tanpa confidence)
result.usage.input_tokens                  # untuk hitung biaya
```

## JavaScript / TypeScript

```bash
npm install @typesafe-ai/sdk      # butuh Node.js 20+
```

```typescript
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();   // baca TYPESAFE_API_KEY dari env

const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    department: choice("Tim mana yang harus menangani ini?", {
      billing: "Pembayaran, invoice, refund",
      technical: "Bug, outage, integrasi",
      sales: null,
    }),
    urgency: score("Seberapa mendesak?", ["rendah", "sedang", "tinggi"]),
    needsHuman: noul("Perlu ditangani manusia."),
  },
});

response.answers.department.choice;      // "billing"
response.answers.department.confidence;  // 0.81
response.answers.urgency.score;          // 1.4
response.answers.needsHuman.noul;        // 0.95
```

Tipe jawaban di-infer dari pertanyaanmu. Paketnya menyertakan ESM, CommonJS,
dan deklarasi TypeScript.

## Pola gerbang tiga jalur

```python
def gate(certainty, act_at, caution_at):
    if certainty >= act_at:      return "act"       # jalan otomatis
    if certainty >= caution_at:  return "caution"   # jalan, tapi tandai
    return "escalate"                                # serahkan ke manusia
```

Ambang mengikuti konsekuensi, contoh:

| Keputusan | `act` | Alasan |
|---|---|---|
| pilih langkah berikutnya | 0.60 | mudah dikoreksi putaran berikutnya |
| nyatakan data sudah cukup | 0.70 | salah berarti fondasi lemah |
| kirim hasil ke manusia | 0.80 | salah berarti membuang waktu orang |

**Kalibrasi bersifat agregat**: dari sekumpulan jawaban berprobabilitas 0,8
sekitar 80% benar. Itu **tidak** menjamin satu jawaban tertentu benar. Pakai
ambang untuk mengatur perilaku sistem, bukan sebagai bukti kebenaran.

## Batas keras

| | |
|---|---|
| Choice | 2–255 opsi |
| Score | 2–10 level |
| Konteks | 64k token total; 32k untuk `state` + pertanyaan terpanjang |
| Input | teks saja (string/objek/array JSON). Tidak ada gambar, audio, video. |

## Harga

Jev 1.13: **$0,042 per juta token input**, token output **gratis**.
10.000 keputusan @ 1.000 token ≈ **$0,42**.

Penghematan fan-out mendekati **N** (jumlah pertanyaan) saat `state`
mendominasi, dan mengecil saat pertanyaan yang mendominasi.

## Error

| Kode | Arti | Tindakan |
|---|---|---|
| 401 | key salah/dicabut | perbarui `TYPESAFE_API_KEY` |
| 422 | bentuk request salah | `criteria`: map untuk choice, array untuk score |
| 429 | rate limit | backoff lalu ulangi |
| 529 | server overload | tunggu sebentar, ulangi |

Lebih lanjut: [reference/troubleshooting.md](reference/troubleshooting.md).

## Keamanan

- Jangan pernah menaruh API key di kode, dokumentasi, atau file konfigurasi
  MCP. Simpan di `.env` (gitignored) atau environment variable.
- Jangan set `TYPESAFE_LOG_LEVEL=debug` pada data nyata: pada level itu SDK
  mencetak body request dan response **tanpa redaksi**.
- `state` yang dikirim tetap pergi ke API TypeSafe. Perlakukan seperti layanan
  pihak ketiga lainnya.

## Implementasi rujukan

Repo skill ini juga memuat implementasi lengkap yang bisa dibaca dan dijalankan:
task router, MCP server, telemetry biaya, dan demo terukur.
Lihat <https://github.com/devnolife/copilot-jev>.

Dokumentasi resmi: <https://docs.typesafe.ai> ·
[API reference](https://docs.typesafe.ai/api) ·
[Playground](https://console.typesafe.ai/playground)