onCheckpoint: async ({ step, infer }) => {
  const res = await infer({
    messages: [
      { role: "user", content: "I can't log in." },
    ],
  });
  console.log(`step=${step} sample=`, await res.text());
}

type Infer = (args: InferArgs) => Promise<Response>;

interface InferArgs {
  messages: ChatMessage[];
  temperature?: number;
  topP?: number;
  maxTokens?: number;
  /** デフォルト: true。SSE ではなく単一 JSON ボディが欲しいなら false に。 */
  stream?: boolean;
  /** OpenAI 互換の Function Calling のためのツール定義。 */
  tools?: ToolDefinition[];
  /** "auto" | "none" | "required" | { type: "function", function: { name } } */
  toolChoice?: ToolChoice;
  /** OpenAI 互換の response_format（text / json_object / json_schema）。 */
  responseFormat?: ResponseFormat;
  /** responseFormat で表現できない制約（regex / choice / grammar）用の vLLM 拡張。 */
  structuredOutputs?: StructuredOutputs;
  signal?: AbortSignal;
}

onCheckpoint: async ({ infer }) => {
  const res = await infer({
    messages: [
      { role: "user", content: "東京の天気は？" },
    ],
    tools: [
      {
        type: "function",
        function: {
          name: "get_weather",
          parameters: {
            type: "object",
            properties: { city: { type: "string" } },
            required: ["city"],
          },
        },
      },
    ],
    toolChoice: "auto",
    stream: false,
  });
  const data = (await res.json()) as { choices: Array<{ message: ChatMessage }> };
  // data.choices[0].message は { role: "assistant", tool_calls: [...] } になり得ます。
};

const res = await infer({
  messages: [{ role: "user", content: "ユーザーのメールアドレスを抽出。" }],
  responseFormat: {
    type: "json_schema",
    json_schema: {
      name: "user",
      schema: {
        type: "object",
        properties: { email: { type: "string", format: "email" } },
        required: ["email"],
      },
      strict: true,
    },
  },
});

const res = await infer({
  messages: [{ role: "user", content: "緊急度を分類: I can't log in." }],
  structuredOutputs: { choice: ["low", "medium", "high"] },
  stream: false,
});

const res = await infer({
  messages: [{ role: "user", content: "チケット ID を生成。" }],
  structuredOutputs: { regex: "^[A-Z]{3}-\\d{4}$" },
  stream: false,
});

const res = await infer({
  messages: [{ role: "user", content: "数字を綴る。" }],
  structuredOutputs: {
    grammar: 'root ::= "zero" | "one" | "two" | "three"',
  },
  stream: false,
});

import type { ChatMessage } from "arkor";

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_weather",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
    },
  },
];

const messages: ChatMessage[] = [
  { role: "user", content: "東京の天気は？" },
];

const first = await infer({ messages, tools, toolChoice: "auto", stream: false });
const firstData = (await first.json()) as { choices: Array<{ message: ChatMessage }> };
const reply = firstData.choices[0].message;

if (reply.role === "assistant" && reply.tool_calls?.length) {
  const call = reply.tool_calls[0];
  const args = JSON.parse(call.function.arguments) as { city: string };
  const result = await getWeather(args.city);

  const second = await infer({
    messages: [
      ...messages,
      reply,                                        // tool_calls を持つ assistant ターン
      { role: "tool", tool_call_id: call.id, content: JSON.stringify(result) },
    ],
    tools,
    toolChoice: "auto",
    stream: false,
  });
  const finalReply = ((await second.json()) as { choices: Array<{ message: ChatMessage }> })
    .choices[0].message;
  // finalReply.content がユーザーに見せる最終回答。
}

export type ChatMessage =
  | { role: "system"; content: string }
  | { role: "user"; content: string }
  | { role: "assistant"; content: string; tool_calls?: ToolCall[] }
  | {
      role: "assistant";
      /** 純粋にツール呼び出しだけのターンでは省略 / null になり得る。 */
      content?: string | null;
      tool_calls: [ToolCall, ...ToolCall[]];
    }
  | { role: "tool"; content: string; tool_call_id: string };

export interface ToolCall {
  id: string;
  type: "function";
  function: {
    name: string;
    /** JSON エンコードされた引数文字列。部分デルタがストリームされ得る。 */
    arguments: string;
  };
}

export interface ToolDefinition {
  type: "function";
  function: {
    name: string;
    description?: string;
    /** ツール引数を表す JSON Schema。 */
    parameters?: Record<string, unknown>;
    strict?: boolean;
  };
}

export type ToolChoice =
  | "auto"
  | "none"
  | "required"
  | { type: "function"; function: { name: string } };

export type ResponseFormat =
  | { type: "text" }
  | { type: "json_object" }
  | {
      type: "json_schema";
      json_schema: {
        name: string;
        description?: string;
        schema: Record<string, unknown>;
        strict?: boolean;
      };
    };

// ヘルパー: ちょうど 1 つのキーを必須化し、他のキーは `never` で禁止する
// レコード型。vLLM の「制約はちょうど 1 つ」という不変条件を型レベルで
// 表現する。SDK 内部の型ですが、下の StructuredOutputs 定義を自己完結に
// するためここでも展開しています。
type ExactlyOne<T> = {
  [K in keyof T]: { [P in K]: T[K] } & {
    [P in Exclude<keyof T, K>]?: never;
  };
}[keyof T];

// `json` / `regex` / `choice` / `grammar` / `json_object` のうち
// ちょうど 1 つを設定。フィールド名は vLLM の wire 形式に合わせて
// snake_case。
export type StructuredOutputs = ExactlyOne<{
  json: Record<string, unknown>;
  regex: string;
  choice: string[];
  grammar: string;
  json_object: true;
}> & {
  disable_any_whitespace?: boolean;
  disable_additional_properties?: boolean;
  whitespace_pattern?: string;
};

// ストリーミング（デフォルト）
const res = await infer({ messages });
for await (const chunk of res.body!) {
  // chunk: 1 つ以上の SSE フレームの Uint8Array
}

// あるいはストリームを一気に読む
const text = await res.text();

// あるいは stream: false にして JSON ボディをパース
const res = await infer({ messages, stream: false });
const data = await res.json();

{
  choices: [
    {
      index: 0,
      finish_reason: "stop" | "length" | "tool_calls" | string,
      message: ChatMessage,
    },
  ],
  // および OpenAI 標準の `id` / `model` / `usage` などバックエンドが付ける拡張フィールド。
}

import { CloudApiError } from "arkor";

try {
  const res = await infer({ messages, ... });
  // 成功時の Response を使う。
} catch (err) {
  if (err instanceof CloudApiError) {
    // err.status は HTTP ステータス、err.message は upstream のメッセージ。
  }
}