@linxiraos/pi-ai 1.0.0

package/src/dialect/qwen3.ts

@@ -0,0 +1,240 @@
+import { parseJsonWithRepair } from "@linxiraos/pi-utils";
+import type { Message, ToolCall } from "../types";
+import { asRecord, mintToolCallId, partialSuffixOverlapAny } from "./coercion";
+import dialectPrompt from "./qwen3.md" with { type: "text" };
+import { renderChatMlTranscript, renderToolResponseResults, stringifyJson } from "./rendering";
+import type {
+	DialectDefinition,
+	DialectRenderOptions,
+	DialectToolResult,
+	InbandScanEvent,
+	InbandScanner,
+	InbandScannerOptions,
+} from "./types";
+
+const TOOL_OPEN = "<tool_call>";
+const TOOL_CLOSE = "</tool_call>";
+const THINK_OPEN = "<think>";
+const THINK_CLOSE = "</think>";
+
+const TOOL_START_TAGS = [TOOL_OPEN] as const;
+const START_TAGS = [TOOL_OPEN, THINK_OPEN] as const;
+const THINK_CLOSE_TAGS = [THINK_CLOSE] as const;
+const COMPLETE_NAME = /^\s*\{\s*"name"\s*:\s*("(?:\\.|[^"\\])*")/;
+
+type State = "outside" | "thinking" | "tool";
+
+export class Qwen3InbandScanner implements InbandScanner {
+	#buffer = "";
+	#state: State = "outside";
+	#id = "";
+	#name = "";
+	#started = false;
+	#thinking = "";
+	readonly #parseThinking: boolean;
+
+	constructor(options: InbandScannerOptions = {}) {
+		this.#parseThinking = options.parseThinking !== false;
+	}
+
+	feed(text: string): InbandScanEvent[] {
+		if (text.length === 0) return [];
+		this.#buffer += text;
+		return this.#consume(false);
+	}
+
+	flush(): InbandScanEvent[] {
+		return this.#consume(true);
+	}
+
+	#consume(final: boolean): InbandScanEvent[] {
+		const events: InbandScanEvent[] = [];
+		while (this.#buffer.length > 0) {
+			if (this.#state === "outside") {
+				this.#consumeOutside(final, events);
+				if (this.#state === "outside") break;
+				continue;
+			}
+
+			if (this.#state === "thinking") {
+				this.#consumeThinking(final, events);
+				if (this.#state === "thinking") break;
+				continue;
+			}
+
+			this.#consumeTool(final, events);
+			if (this.#state === "tool") break;
+		}
+		if (final && this.#state === "thinking") this.#endThinking(events);
+		return events;
+	}
+
+	#consumeOutside(final: boolean, events: InbandScanEvent[]): void {
+		const tool = this.#buffer.indexOf(TOOL_OPEN);
+		const think = this.#parseThinking ? this.#buffer.indexOf(THINK_OPEN) : -1;
+		let start = tool;
+		let isThink = false;
+		if (think !== -1 && (start === -1 || think < start)) {
+			start = think;
+			isThink = true;
+		}
+
+		if (start === -1) {
+			const tags = this.#parseThinking ? START_TAGS : TOOL_START_TAGS;
+			const hold = final ? 0 : partialSuffixOverlapAny(this.#buffer, tags);
+			const emit = this.#buffer.slice(0, this.#buffer.length - hold);
+			if (emit.length > 0) events.push({ type: "text", text: emit });
+			this.#buffer = this.#buffer.slice(this.#buffer.length - hold);
+			return;
+		}
+
+		if (start > 0) events.push({ type: "text", text: this.#buffer.slice(0, start) });
+		if (isThink) {
+			this.#buffer = this.#buffer.slice(start + THINK_OPEN.length);
+			this.#state = "thinking";
+			this.#thinking = "";
+			events.push({ type: "thinkingStart" });
+			return;
+		}
+
+		this.#buffer = this.#buffer.slice(start + TOOL_OPEN.length);
+		this.#state = "tool";
+		this.#id = mintToolCallId();
+		this.#name = "";
+		this.#started = false;
+	}
+
+	#consumeThinking(final: boolean, events: InbandScanEvent[]): void {
+		const close = this.#buffer.indexOf(THINK_CLOSE);
+		if (close === -1) {
+			const hold = final ? 0 : partialSuffixOverlapAny(this.#buffer, THINK_CLOSE_TAGS);
+			const delta = this.#buffer.slice(0, this.#buffer.length - hold);
+			this.#emitThinkingDelta(delta, events);
+			this.#buffer = this.#buffer.slice(this.#buffer.length - hold);
+			if (final) this.#endThinking(events);
+			return;
+		}
+
+		this.#emitThinkingDelta(this.#buffer.slice(0, close), events);
+		this.#buffer = this.#buffer.slice(close + THINK_CLOSE.length);
+		this.#endThinking(events);
+	}
+
+	#consumeTool(final: boolean, events: InbandScanEvent[]): void {
+		const close = this.#buffer.indexOf(TOOL_CLOSE);
+		const body = close === -1 ? this.#buffer : this.#buffer.slice(0, close);
+		if (!this.#started) this.#tryStart(body, events);
+		if (close === -1) {
+			if (final) this.#resetTool();
+			return;
+		}
+
+		const parsed = this.#parseCall(body);
+		if (parsed) {
+			if (!this.#started) {
+				events.push({ type: "toolStart", id: this.#id, name: parsed.name });
+				this.#started = true;
+			}
+			events.push({
+				type: "toolEnd",
+				id: this.#id,
+				name: parsed.name,
+				arguments: parsed.arguments,
+				rawBlock: `${TOOL_OPEN}${body}${TOOL_CLOSE}`,
+			});
+		}
+		this.#buffer = this.#buffer.slice(close + TOOL_CLOSE.length);
+		this.#resetTool();
+	}
+
+	#emitThinkingDelta(delta: string, events: InbandScanEvent[]): void {
+		if (delta.length === 0) return;
+		this.#thinking += delta;
+		events.push({ type: "thinkingDelta", delta });
+	}
+
+	#endThinking(events: InbandScanEvent[]): void {
+		events.push({ type: "thinkingEnd", thinking: this.#thinking });
+		this.#thinking = "";
+		this.#state = "outside";
+	}
+
+	#tryStart(body: string, events: InbandScanEvent[]): void {
+		const nameMatch = COMPLETE_NAME.exec(body);
+		if (!nameMatch) return;
+		let name: unknown;
+		try {
+			name = JSON.parse(nameMatch[1]!);
+		} catch {
+			return;
+		}
+		if (typeof name !== "string" || name.length === 0) return;
+		this.#name = name;
+		this.#started = true;
+		events.push({ type: "toolStart", id: this.#id, name: this.#name });
+	}
+
+	#parseCall(body: string): { name: string; arguments: Record<string, unknown> } | undefined {
+		try {
+			const parsed = parseJsonWithRepair<{ name?: unknown; arguments?: unknown }>(body.trim());
+			if (typeof parsed.name !== "string" || parsed.name.length === 0) return undefined;
+			let args = parsed.arguments;
+			if (typeof args === "string") {
+				try {
+					args = parseJsonWithRepair<unknown>(args);
+				} catch {
+					args = {};
+				}
+			}
+			return { name: parsed.name, arguments: asRecord(args) };
+		} catch {
+			return undefined;
+		}
+	}
+
+	#resetTool(): void {
+		this.#state = "outside";
+		this.#id = "";
+		this.#name = "";
+		this.#started = false;
+	}
+}
+
+function renderToolCall(call: ToolCall, _options: DialectRenderOptions = {}): string {
+	return `${TOOL_OPEN}\n${stringifyJson({ name: call.name, arguments: call.arguments })}\n${TOOL_CLOSE}`;
+}
+
+function renderAssistantToolCalls(calls: readonly ToolCall[], options: DialectRenderOptions = {}): string {
+	return calls.map(call => renderToolCall(call, options)).join("\n");
+}
+
+function renderToolResults(results: readonly DialectToolResult[], _options: DialectRenderOptions = {}): string {
+	return renderToolResponseResults(results);
+}
+
+function renderThinking(text: string): string {
+	if (!text) return "";
+	return `${THINK_OPEN}\n${text}\n${THINK_CLOSE}`;
+}
+
+function renderTranscript(messages: readonly Message[], options: DialectRenderOptions = {}): string {
+	return renderChatMlTranscript(messages, options, {
+		toolResultRole: "user",
+		renderThinking,
+		renderCalls: renderAssistantToolCalls,
+		renderResultsBody: renderToolResults,
+	});
+}
+
+const definition: DialectDefinition = {
+	dialect: "qwen3",
+	prompt: dialectPrompt,
+	createScanner: options => new Qwen3InbandScanner(options),
+	renderToolCall,
+	renderAssistantToolCalls,
+	renderToolResults,
+	renderThinking,
+	renderTranscript,
+};
+
+export default definition;

package/src/dialect/rendering.ts

@@ -0,0 +1,304 @@
+import { stringifyJson as stringifyJsonValue } from "@linxiraos/pi-utils";
+import type { AssistantMessage, Message, ToolCall, ToolResultMessage } from "../types";
+import type { DialectRenderOptions, DialectToolResult } from "./types";
+
+export function renderToolResponseResults(results: readonly DialectToolResult[]): string {
+	return results.map(result => `<tool_response>\n${result.text}\n</tool_response>`).join("\n");
+}
+
+export function kimiCallId(name: string, id: string, index: number): string {
+	const trimmed = id.trim();
+	return trimmed.startsWith("functions.") ? trimmed : `functions.${name}:${index}`;
+}
+
+export function harmonyRecipient(name: string): string {
+	return name.startsWith("functions.") ? name : `functions.${name}`;
+}
+
+export function stringifyJson(value: unknown): string {
+	return stringifyJsonValue(value) ?? "null";
+}
+
+/**
+ * Render `name(key=value, …)` with Python-literal argument values. Top-level
+ * multiline strings render as verbatim `"""…"""` blocks so payload-carrying
+ * args (file content, scripts, patches) keep real newlines instead of `\n`
+ * escape soup; nested values always use escaped single-line literals.
+ */
+export function pyCall(name: string, args: Record<string, unknown>): string {
+	let kwargs = "";
+	for (const key in args) {
+		kwargs += `${kwargs ? ", " : ""}${key}=${pyArgValue(args[key])}`;
+	}
+	return `${name}(${kwargs})`;
+}
+
+function pyArgValue(value: unknown): string {
+	if (typeof value === "string" && value.includes("\n")) {
+		// Verbatim `"""` fencing is only unambiguous when the content cannot
+		// collide with the fence: no `"""` inside, no quote butting against a
+		// fence edge, no trailing backslash swallowing the closer.
+		const fenceSafe =
+			!value.includes('"""') && !value.startsWith('"') && !value.endsWith('"') && !value.endsWith("\\");
+		if (fenceSafe) return `"""${value}"""`;
+	}
+	return pyValue(value);
+}
+
+/** Render a JSON-ish value as a Python literal (`True`/`False`/`None`, escaped strings, lists, dicts). */
+export function pyValue(value: unknown): string {
+	if (value === null || value === undefined) return "None";
+	if (typeof value === "boolean") return value ? "True" : "False";
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : pyString(String(value));
+	if (typeof value === "string") return pyString(value);
+	if (Array.isArray(value)) return `[${value.map(pyValue).join(", ")}]`;
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		let entries = "";
+		for (const key in record) {
+			entries += `${entries ? ", " : ""}${pyString(key)}: ${pyValue(record[key])}`;
+		}
+		return `{${entries}}`;
+	}
+	return pyString(String(value));
+}
+
+function pyString(value: string): string {
+	const escaped = value
+		.replaceAll("\\", "\\\\")
+		.replaceAll('"', '\\"')
+		.replaceAll("\n", "\\n")
+		.replaceAll("\r", "\\r")
+		.replaceAll("\t", "\\t");
+	return `"${escaped}"`;
+}
+
+export function escapeXmlAttr(value: string): string {
+	return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function escapeXmlText(value: string): string {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export type AssistantTranscriptParts = {
+	readonly text: string;
+	readonly thinking: string;
+	readonly toolCalls: readonly ToolCall[];
+};
+
+export type ToolCallRenderer = (calls: readonly ToolCall[], options?: DialectRenderOptions) => string;
+export type ToolResultRenderer = (results: readonly DialectToolResult[], options?: DialectRenderOptions) => string;
+
+export type ChatMlTranscriptConfig = {
+	readonly bos?: string;
+	readonly toolResultRole: "tool" | "user";
+	readonly renderThinking: (text: string) => string;
+	readonly renderCalls: ToolCallRenderer;
+	readonly renderResultsBody: ToolResultRenderer;
+};
+
+export type LegacyTextTranscriptConfig = {
+	readonly renderThinking: (text: string) => string;
+	readonly renderCalls: ToolCallRenderer;
+	readonly renderResults: ToolResultRenderer;
+};
+
+export function renderChatMlTranscript(
+	messages: readonly Message[],
+	options: DialectRenderOptions,
+	config: ChatMlTranscriptConfig,
+): string {
+	if (messages.length === 0) return "";
+	let out = config.bos ?? "";
+	for (let i = 0; i < messages.length; ) {
+		const message = messages[i]!;
+		if (message.role === "assistant") {
+			const parts = assistantTranscriptParts(message);
+			out += chatMlTurn(
+				"assistant",
+				`${config.renderThinking(parts.thinking)}${parts.text}${config.renderCalls(parts.toolCalls, options)}`,
+			);
+			i++;
+			continue;
+		}
+		if (message.role === "toolResult") {
+			const run = collectToolResultRun(messages, i);
+			out += chatMlTurn(config.toolResultRole, config.renderResultsBody(run.results, options));
+			i = run.next;
+			continue;
+		}
+		const role = message.role === "developer" ? "system" : message.role;
+		out += chatMlTurn(role, messageContentText(message.content));
+		i++;
+	}
+	return out;
+}
+
+export function renderLegacyTextTranscript(
+	messages: readonly Message[],
+	options: DialectRenderOptions,
+	config: LegacyTextTranscriptConfig,
+): string {
+	let out = "";
+	for (let i = 0; i < messages.length; ) {
+		const message = messages[i]!;
+		if (message.role === "assistant") {
+			const parts = assistantTranscriptParts(message);
+			out = appendLegacySegment(
+				out,
+				`Assistant: ${config.renderThinking(parts.thinking)}${parts.text}${config.renderCalls(parts.toolCalls, options)}`,
+			);
+			i++;
+			continue;
+		}
+		if (message.role === "toolResult") {
+			const run = collectToolResultRun(messages, i);
+			out = appendLegacySegment(out, `Human: ${config.renderResults(run.results, options)}`);
+			i = run.next;
+			continue;
+		}
+		const text = messageContentText(message.content);
+		out = message.role === "developer" ? appendLegacyPlain(out, text) : appendLegacySegment(out, `Human: ${text}`);
+		i++;
+	}
+	return out;
+}
+
+export function assistantTranscriptParts(message: AssistantMessage): AssistantTranscriptParts {
+	let text = "";
+	const thinking: string[] = [];
+	const toolCalls: ToolCall[] = [];
+	for (const block of message.content) {
+		if (block.type === "text") text += block.text;
+		else if (block.type === "thinking") thinking.push(block.thinking);
+		else if (block.type === "toolCall") toolCalls.push(block);
+	}
+	return { text, thinking: thinking.join("\n"), toolCalls };
+}
+
+export function collectToolResultRun(
+	messages: readonly Message[],
+	start: number,
+): { readonly results: readonly DialectToolResult[]; readonly next: number } {
+	const results: DialectToolResult[] = [];
+	let next = start;
+	while (next < messages.length && messages[next]!.role === "toolResult") {
+		results.push(toolResultToDialectResult(messages[next] as ToolResultMessage, results.length));
+		next++;
+	}
+	return { results, next };
+}
+
+function toolResultToDialectResult(message: ToolResultMessage, index: number): DialectToolResult {
+	return {
+		id: message.toolCallId,
+		name: message.toolName,
+		index,
+		text: messageContentText(message.content),
+		isError: message.isError,
+	};
+}
+
+export function messageContentText(
+	content: string | readonly { readonly type: string; readonly text?: string; readonly mimeType?: string }[],
+): string {
+	if (typeof content === "string") return content;
+	let text = "";
+	for (const block of content) {
+		if (block.type === "text" && block.text !== undefined) text += block.text;
+		else if (block.type === "image") text += block.mimeType ? `[Image: ${block.mimeType}]` : "[Image]";
+	}
+	return text;
+}
+
+function isAsciiWhitespace(code: number): boolean {
+	return code === 9 || code === 10 || code === 11 || code === 12 || code === 13 || code === 32;
+}
+
+function trimAsciiStart(text: string, start: number, end: number): number {
+	let cursor = start;
+	while (cursor < end && isAsciiWhitespace(text.charCodeAt(cursor))) cursor++;
+	return cursor;
+}
+
+function trimAsciiEnd(text: string, start: number, end: number): number {
+	let cursor = end;
+	while (cursor > start && isAsciiWhitespace(text.charCodeAt(cursor - 1))) cursor--;
+	return cursor;
+}
+
+function findDelimitedThinkingClose(open: string, close: string, text: string, start: number, end: number): number {
+	let depth = 1;
+	let cursor = start;
+	while (cursor < end) {
+		const nextClose = text.indexOf(close, cursor);
+		if (nextClose < 0 || nextClose >= end) return -1;
+		const nextOpen = text.indexOf(open, cursor);
+		if (nextOpen >= 0 && nextOpen < nextClose) {
+			depth++;
+			cursor = nextOpen + open.length;
+			continue;
+		}
+		depth--;
+		if (depth === 0) return nextClose;
+		cursor = nextClose + close.length;
+	}
+	return -1;
+}
+
+function unwrapDelimitedThinking(open: string, close: string, text: string): string {
+	const end = trimAsciiEnd(text, 0, text.length);
+	let cursor = trimAsciiStart(text, 0, end);
+	if (cursor >= end || !text.startsWith(open, cursor)) return text;
+
+	const segments: string[] = [];
+	while (cursor < end) {
+		if (!text.startsWith(open, cursor)) return text;
+		const innerStart = cursor + open.length;
+		const innerEnd = findDelimitedThinkingClose(open, close, text, innerStart, end);
+		if (innerEnd < 0) return text;
+
+		const trimmedInnerEnd = trimAsciiEnd(text, innerStart, innerEnd);
+		const trimmedInnerStart = trimAsciiStart(text, innerStart, trimmedInnerEnd);
+		segments.push(unwrapDelimitedThinking(open, close, text.slice(trimmedInnerStart, trimmedInnerEnd)));
+		cursor = trimAsciiStart(text, innerEnd + close.length, end);
+	}
+	return segments.join("\n");
+}
+
+export function renderDelimitedThinking(open: string, close: string, text: string): string {
+	if (!text) return "";
+	return `${open}\n${unwrapDelimitedThinking(open, close, text)}\n${close}`;
+}
+
+export function chatMlTurn(role: "assistant" | "system" | "tool" | "user", body: string): string {
+	return `<|im_start|>${role}\n${body}<|im_end|>\n`;
+}
+
+export function kimiTurn(role: "assistant" | "system" | "user", name: string, body: string): string {
+	return `<|im_${role}|>${name}<|im_middle|>${body}<|im_end|>`;
+}
+
+export function gemmaTurn(role: "model" | "system" | "user", body: string): string {
+	return `<|turn>${role}\n${body}<turn|>`;
+}
+
+export function geminiTurn(role: "model" | "user", body: string): string {
+	return `<start_of_turn>${role}\n${body}<end_of_turn>\n`;
+}
+
+export function joinUserBodies(left: string, right: string): string {
+	if (!left) return right;
+	if (!right) return left;
+	return `${left}\n${right}`;
+}
+
+function appendLegacyPlain(out: string, text: string): string {
+	if (!text) return out;
+	return out ? `${out}\n\n${text}` : text;
+}
+
+function appendLegacySegment(out: string, segment: string): string {
+	return `${out}\n\n${segment}`;
+}