@tasco/ai/eval

Bộ chạy eval prompt qua gateway, dùng trong script và CI (chỉ chạy trên Node).

Hàm

callGateway()

function callGateway(messages, options): Promise<string>;

Gọi gateway 1 lượt, trả content assistant (ném lỗi khi HTTP/shape sai).

Tham số

Tham số	Kiểu
messages	ChatMessage[]
options	EvalRunOptions

Trả về

Promise<string>

---

checkAssertion()

function checkAssertion(output, a): AssertionResult;

Kiểm một assertion trên output model — hàm thuần, tất định.

Tham số

Tham số	Kiểu
output	string
a	Assertion

Trả về

AssertionResult

---

formatReport()

function formatReport(results): string;

Báo cáo markdown cho log CI: dòng tổng, từng case và assertion, output rút gọn của case trượt.

Tham số

Tham số	Kiểu
results	EvalCaseResult[]

Trả về

string

---

runEvalCase()

function runEvalCase(c, options): Promise<EvalCaseResult>;

Chạy một case; lỗi gateway ghi vào error của kết quả thay vì ném ra.

Tham số

Tham số	Kiểu
c	EvalCase
options	EvalRunOptions

Trả về

Promise<EvalCaseResult>

---

runEvalSuite()

function runEvalSuite(cases, options): Promise<EvalCaseResult[]>;

Chạy tuần tự cả bộ case (không song song, để không dội rate limit của gateway).

Tham số

Tham số	Kiểu
cases	EvalCase[]
options	EvalRunOptions

Trả về

Promise<EvalCaseResult[]>

---

summarize()

function summarize(results): EvalSummary;

Đếm case đạt/trượt.

Tham số

Tham số	Kiểu
results	EvalCaseResult[]

Trả về

EvalSummary

Interface

AssertionResult

Kết quả một assertion.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
detail	string	Mô tả ngắn để in report khi fail.
pass	boolean	Output thoả điều kiện.

---

EvalCase

Một ca eval: hội thoại gửi model và các điều kiện output phải thoả.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
assertions	Assertion[]	Mọi assertion phải đạt thì case mới pass.
id	string	Định danh case, nên tiền tố theo prompt id: "extract-json/don-hang".
messages	ChatMessage[]	Hội thoại gửi gateway, thường gồm system prompt render từ prompt library.

---

EvalCaseResult

Kết quả chạy một case.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
assertions	AssertionResult[]	Kết quả từng assertion (cùng thứ tự với case.assertions).
error?	string	Lỗi hạ tầng (gateway chết, timeout…) — khác với assertion fail.
id	string	id của case.
output	string	Output model (cắt gọn khi in report).
pass	boolean	Mọi assertion đạt và không có lỗi hạ tầng.

---

EvalRunOptions

Cấu hình gọi gateway khi chạy eval.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
apiKey	string	Key của gateway — lấy từ biến môi trường, không hardcode.
fetch?	{ (input, init?): Promise<Response>; (input, init?): Promise<Response>; }	fetch tuỳ biến (phục vụ test). Mặc định globalThis.fetch.
gatewayUrl	string	URL gốc gateway OpenAI-compatible (có /v1).
model	string	Model chạy eval.
temperature?	number	Nhiệt độ thấp mặc định (0) để output ổn định giữa các lần chạy CI.

---

EvalSummary

Số liệu tổng của một lần chạy eval.

Thuộc tính

Thuộc tính	Kiểu	Mô tả
failed	number	Số case trượt, kể cả case lỗi hạ tầng.
passed	number	Số case đạt.
total	number	Tổng số case.

Kiểu

Assertion

type Assertion = 
  | {
  ignoreCase?: boolean;
  type: "contains";
  value: string;
}
  | {
  ignoreCase?: boolean;
  type: "not-contains";
  value: string;
}
  | {
  flags?: string;
  pattern: string;
  type: "regex";
}
  | {
  type: "max-chars";
  value: number;
}
  | {
  type: "json-valid";
}
  | {
  type: "max-lines";
  value: number;
};

Một điều kiện kiểm output model: contains/not-contains (chuỗi con), regex, max-chars, max-lines (không đếm dòng trống), json-valid (chấp nhận JSON bọc trong code fence).