typia 14.0.6 → 15.0.0

package/src/llm.ts

@@ -2,6 +2,7 @@ import {
   IJsonParseResult,
   ILlmApplication,
   ILlmController,
+  ILlmEvaluation,
   ILlmSchema,
   ILlmStructuredOutput,
 } from "@typia/interface";
@@ -201,6 +202,69 @@ export function structuredOutput(): never {
   NoTransformConfigurationError("llm.structuredOutput");
 }
 
+/* -----------------------------------------------------------
+  EVALUATION
+----------------------------------------------------------- */
+/**
+ * Creates LLM evaluation questions.
+ *
+ * @danger You must configure the generic argument `T`
+ */
+export function evaluation(): never;
+
+/**
+ * Creates LLM evaluation questions from TypeScript object type.
+ *
+ * Generates {@link ILlmEvaluation} for evaluation models, which answer typed
+ * questions about a shared state with probabilities instead of generating text:
+ * TypeSafe's Jev natively, and OpenAI, Anthropic, and Google through Vercel AI
+ * SDK's `experimental_evaluate()`.
+ *
+ * Every leaf property of `T` becomes one question, and its JSDoc description
+ * becomes the question text:
+ *
+ * - `boolean` → boolean question
+ * - String enum or string literal union → choice question
+ * - Numeric enum or numeric literal union → score question
+ * - Array of a string literal union or string enum → one boolean question per
+ *   member
+ * - Nested object → flattened, one question per leaf
+ *
+ * Types an evaluation model cannot answer, such as `string`, `number`, optional
+ * properties, or a leaf without a JSDoc description, are compile errors. Use
+ * `tags.Probability<N>` or `@probability N` to set decision thresholds and
+ * acceptance minimums. Once one choice, score, or set member declares a
+ * requirement, every member must declare one or inherit the property's
+ * `@probability` default. A nested object's own JSDoc description is not sent
+ * to the model; only the leaves' descriptions become question text. Other
+ * validation refinements that the answer decoder cannot enforce are compile
+ * errors.
+ *
+ * This feature is experimental. It follows Vercel AI SDK's evaluation model
+ * specification, which is itself experimental and may change in patch
+ * releases.
+ *
+ * Workflow:
+ *
+ * 1. Pass {@link ILlmEvaluation.questions} to the evaluation model
+ * 2. Receive the answer map keyed by the same question IDs
+ * 3. Use {@link ILlmEvaluation.decode} to fold the answers back into `T`; pass the
+ *    model's declared rounding precision when available
+ *
+ * Related functions:
+ *
+ * - {@link structuredOutput} — Structured output generated as text by an LLM
+ *
+ * @template T Target decision type (object with static properties)
+ * @returns LLM evaluation questions with a checked answer decoder
+ */
+export function evaluation<T extends Record<string, any>>(): ILlmEvaluation<T>;
+
+/** @internal */
+export function evaluation(): never {
+  NoTransformConfigurationError("llm.evaluation");
+}
+
 /* -----------------------------------------------------------
   RAW SCHEMAS
 ----------------------------------------------------------- */

package/src/re-exports.ts

@@ -25,6 +25,7 @@ export type {
   ILlmApplication,
   ILlmFunction,
   ILlmStructuredOutput,
+  ILlmEvaluation,
   ILlmSchema,
   // reflect
   IMetadataSchema,