@linxiraos/pi-ai 1.0.0

package/src/providers/google-types.ts

@@ -0,0 +1,180 @@
+/**
+ * Local mirror of the subset of `@google/genai` types this package consumes.
+ *
+ * Field shapes match Gemini / Vertex AI wire format 1:1. Enum-shaped values are
+ * modelled as string literal unions so they pass through `JSON.stringify` and
+ * `JSON.parse` unchanged.
+ *
+ * Keep this file in sync with the actual request/response surface of:
+ *   - `POST {generativelanguage,aiplatform}.googleapis.com/.../models/{model}:streamGenerateContent?alt=sse`
+ *   - The Cloud Code Assist endpoint used by `google-gemini-cli.ts`
+ */
+/** Mirror of `@google/genai`'s `FinishReason` string enum. */
+export type FinishReason =
+	| "FINISH_REASON_UNSPECIFIED"
+	| "STOP"
+	| "MAX_TOKENS"
+	| "SAFETY"
+	| "RECITATION"
+	| "LANGUAGE"
+	| "OTHER"
+	| "BLOCKLIST"
+	| "PROHIBITED_CONTENT"
+	| "SPII"
+	| "MALFORMED_FUNCTION_CALL"
+	| "IMAGE_SAFETY"
+	| "IMAGE_PROHIBITED_CONTENT"
+	| "IMAGE_RECITATION"
+	| "IMAGE_OTHER"
+	| "UNEXPECTED_TOOL_CALL"
+	| "NO_IMAGE";
+
+/** Mirror of `@google/genai`'s `FunctionCallingConfigMode` string enum. */
+export type FunctionCallingConfigMode = "MODE_UNSPECIFIED" | "AUTO" | "NONE" | "ANY" | "VALIDATED";
+
+/** Mirror of `@google/genai`'s `ThinkingLevel` string enum. */
+export type ThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+
+/** Inline base64-encoded data part. */
+export interface InlineDataPart {
+	mimeType: string;
+	data: string;
+}
+
+/** Function call emitted by the model. */
+export interface FunctionCallPart {
+	name?: string;
+	args?: Record<string, unknown>;
+	id?: string;
+}
+
+/** Tool execution result fed back to the model. */
+export interface FunctionResponsePart {
+	name: string;
+	response: Record<string, unknown>;
+	parts?: Part[];
+	id?: string;
+}
+
+/**
+ * A single piece of a `Content` message. Mirrors the SDK's union by keeping
+ * every optional field — the model and the wire treat shape as discriminator.
+ */
+export interface Part {
+	text?: string;
+	thought?: boolean;
+	thoughtSignature?: string;
+	inlineData?: InlineDataPart;
+	functionCall?: FunctionCallPart;
+	functionResponse?: FunctionResponsePart;
+}
+
+/** Conversation turn. Roles: `"user"`, `"model"`, optionally absent for system instructions. */
+export interface Content {
+	role?: string;
+	parts?: Part[];
+}
+
+/** Thinking/reasoning configuration shared by Gemini 2.x and 3.x models. */
+export interface ThinkingConfig {
+	includeThoughts?: boolean;
+	thinkingBudget?: number;
+	thinkingLevel?: ThinkingLevel;
+}
+
+/** Function declaration entry inside `tools[].functionDeclarations`. */
+export interface FunctionDeclaration {
+	name: string;
+	description?: string;
+	parameters?: Record<string, unknown>;
+	parametersJsonSchema?: Record<string, unknown>;
+}
+
+/** Tool group as accepted at the request top level. */
+export interface ToolDeclaration {
+	functionDeclarations: Record<string, unknown>[];
+}
+
+/** Tool selection mode container. */
+export interface ToolConfig {
+	functionCallingConfig?: {
+		mode: FunctionCallingConfigMode;
+		allowedFunctionNames?: string[];
+	};
+}
+
+/**
+ * Generation/sampling and request-shape options passed via the SDK's `config`.
+ *
+ * Fields that the wire format places at the request body root (systemInstruction,
+ * tools, toolConfig, safetySettings, cachedContent) live here too — the
+ * transformer in `google-shared.ts` lifts them out when serializing.
+ */
+export interface GenerateContentConfig {
+	temperature?: number;
+	maxOutputTokens?: number;
+	topP?: number;
+	topK?: number;
+	candidateCount?: number;
+	stopSequences?: string[];
+	presencePenalty?: number;
+	frequencyPenalty?: number;
+	seed?: number;
+	responseMimeType?: string;
+	responseSchema?: Record<string, unknown>;
+	responseJsonSchema?: Record<string, unknown>;
+	responseModalities?: string[];
+	systemInstruction?: Content | { role?: string; parts: { text: string }[] };
+	tools?: ToolDeclaration[];
+	toolConfig?: ToolConfig;
+	safetySettings?: Array<Record<string, unknown>>;
+	cachedContent?: string;
+	thinkingConfig?: ThinkingConfig;
+	/**
+	 * Gemini/Vertex serving tier. Serialized to the request body root as
+	 * `serviceTier` (camelCase) by the transformer in `google-shared.ts`.
+	 */
+	serviceTier?: "auto" | "default" | "flex" | "scale" | "priority";
+	abortSignal?: AbortSignal;
+}
+
+/** Top-level argument to `generateContentStream`. */
+export interface GenerateContentParameters {
+	model: string;
+	contents: Content[];
+	config?: GenerateContentConfig;
+}
+
+/** Per-stream candidate envelope. */
+export interface Candidate {
+	content?: Content;
+	finishReason?: FinishReason;
+	index?: number;
+}
+
+/** Cumulative token accounting attached to the trailing chunk. */
+export interface UsageMetadata {
+	promptTokenCount?: number;
+	candidatesTokenCount?: number;
+	thoughtsTokenCount?: number;
+	totalTokenCount?: number;
+	cachedContentTokenCount?: number;
+}
+
+/** Prompt-level safety feedback; `blockReason` is set (with no candidates) when the prompt is blocked. */
+export interface PromptFeedback {
+	blockReason?: string;
+	blockReasonMessage?: string;
+	[key: string]: unknown;
+}
+
+/** Single SSE chunk's parsed JSON body. */
+export interface GenerateContentResponse {
+	candidates?: Candidate[];
+	usageMetadata?: UsageMetadata;
+	modelVersion?: string;
+	responseId?: string;
+	promptFeedback?: PromptFeedback;
+	/** In-band stream failure (quota, internal error) delivered as a final JSON event. */
+	error?: { code?: number; message?: string; status?: string };
+}

package/src/providers/google-vertex.ts

@@ -0,0 +1,135 @@
+import { resolveVertexEndpointHost } from "@linxiraos/pi-catalog/hosts";
+import { $env } from "@linxiraos/pi-utils";
+import * as AIError from "../error";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { getVertexAccessToken } from "./google-auth";
+import {
+	buildGoogleGenerateContentParams,
+	type GoogleGenAIRequestPlan,
+	type GoogleSharedStreamOptions,
+	streamGoogleGenAI,
+} from "./google-shared";
+
+export interface GoogleVertexOptions extends GoogleSharedStreamOptions {
+	project?: string;
+	location?: string;
+}
+
+const API_VERSION = "v1";
+
+export const streamGoogleVertex: StreamFunction<"google-vertex"> = (
+	model: Model<"google-vertex">,
+	context: Context,
+	options?: GoogleVertexOptions,
+): AssistantMessageEventStream => {
+	return streamGoogleGenAI({
+		model,
+		options,
+		api: "google-vertex",
+		retainTextSignature: true,
+		prepare: async (): Promise<GoogleGenAIRequestPlan> => {
+			const apiKey = resolveApiKey(options);
+			const params = buildGoogleGenerateContentParams(model, context, options ?? {});
+			params.config ||= {};
+			if (!params.config.safetySettings) {
+				params.config.safetySettings = [
+					{
+						category: "HARM_CATEGORY_HATE_SPEECH",
+						threshold: "OFF",
+					},
+					{
+						category: "HARM_CATEGORY_DANGEROUS_CONTENT",
+						threshold: "OFF",
+					},
+					{
+						category: "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+						threshold: "OFF",
+					},
+					{
+						category: "HARM_CATEGORY_HARASSMENT",
+						threshold: "OFF",
+					},
+				];
+			}
+			const baseHeaders: Record<string, string> = {
+				...(model.headers ?? {}),
+				...(options?.headers ?? {}),
+			};
+			// Vertex AI ignores a `serviceTier` request-body field (unlike the direct
+			// Gemini API); priority must travel as a request header. Only `priority`
+			// has a documented Vertex request control — `flex` has none, so it's a no-op.
+			if (options?.serviceTier === "priority") {
+				baseHeaders["X-Vertex-AI-LLM-Shared-Request-Type"] = "priority";
+			}
+
+			if (apiKey) {
+				// Explicit `location` is a deliberate residency choice: honor it and let
+				// a 404 surface. An ambient env-derived region falls back to the global
+				// endpoint so a stray GOOGLE_*_LOCATION never breaks a previously-working
+				// global-only request.
+				const explicitLocation = options?.location;
+				const location = explicitLocation ?? resolveAmbientLocation() ?? "global";
+				const host = resolveVertexEndpointHost(location);
+				const path = `${API_VERSION}/publishers/google/models/${model.id}:streamGenerateContent?alt=sse`;
+				const useGlobalFallback = !explicitLocation && host !== "aiplatform.googleapis.com";
+				return {
+					params,
+					url: `https://${host}/${path}`,
+					fallbackUrl: useGlobalFallback ? `https://aiplatform.googleapis.com/${path}` : undefined,
+					headers: {
+						...baseHeaders,
+						"x-goog-api-key": apiKey,
+					},
+					fetch: options?.fetch,
+				};
+			}
+
+			const project = resolveProject(options);
+			const location = resolveLocation(options);
+			const accessToken = await getVertexAccessToken({ signal: options?.signal, fetch: options?.fetch });
+			const host = resolveVertexEndpointHost(location);
+			const url = `https://${host}/${API_VERSION}/projects/${project}/locations/${location}/publishers/google/models/${model.id}:streamGenerateContent?alt=sse`;
+			return {
+				params,
+				url,
+				headers: { ...baseHeaders, Authorization: `Bearer ${accessToken}` },
+				fetch: options?.fetch,
+			};
+		},
+	});
+};
+
+function resolveApiKey(options?: GoogleVertexOptions): string | undefined {
+	// options.apiKey may contain sentinel values like "<authenticated>" or "N/A"
+	// leaked from the agent loop — only use it if it looks like a real API key.
+	const optKey = options?.apiKey;
+	const realKey = optKey && !optKey.startsWith("<") && optKey !== "N/A" ? optKey : undefined;
+	return realKey || $env.GOOGLE_CLOUD_API_KEY;
+}
+
+function resolveProject(options?: GoogleVertexOptions): string {
+	const project = options?.project || $env.GOOGLE_CLOUD_PROJECT || $env.GCP_PROJECT || $env.GCLOUD_PROJECT;
+	if (!project) {
+		throw new AIError.ConfigurationError(
+			"Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCP_PROJECT/GCLOUD_PROJECT or pass project in options.",
+		);
+	}
+	return project;
+}
+
+function resolveAmbientLocation(): string | undefined {
+	return $env.GOOGLE_VERTEX_LOCATION || $env.GOOGLE_CLOUD_LOCATION || $env.VERTEX_LOCATION || undefined;
+}
+function resolveOptionalLocation(options?: GoogleVertexOptions): string | undefined {
+	return options?.location || resolveAmbientLocation();
+}
+function resolveLocation(options?: GoogleVertexOptions): string {
+	const location = resolveOptionalLocation(options);
+	if (!location) {
+		throw new AIError.ConfigurationError(
+			"Vertex AI requires a location. Set GOOGLE_VERTEX_LOCATION/GOOGLE_CLOUD_LOCATION/VERTEX_LOCATION or pass location in options.",
+		);
+	}
+	return location;
+}

package/src/providers/google.ts

@@ -0,0 +1,47 @@
+import * as AIError from "../error";
+import { getEnvApiKey } from "../stream";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import {
+	buildGoogleGenerateContentParams,
+	type GoogleGenAIRequestPlan,
+	type GoogleSharedStreamOptions,
+	streamGoogleGenAI,
+} from "./google-shared";
+
+export type GoogleOptions = GoogleSharedStreamOptions;
+
+const DEFAULT_GENERATIVE_LANGUAGE_BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+export const streamGoogle: StreamFunction<"google-generative-ai"> = (
+	model: Model<"google-generative-ai">,
+	context: Context,
+	options?: GoogleOptions,
+): AssistantMessageEventStream => {
+	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
+	if (!apiKey) {
+		throw new AIError.MissingApiKeyError(
+			undefined,
+			"Google Generative AI requires an API key (GEMINI_API_KEY or options.apiKey).",
+		);
+	}
+
+	return streamGoogleGenAI({
+		model,
+		options,
+		api: "google-generative-ai",
+		prepare: (): GoogleGenAIRequestPlan => {
+			const params = buildGoogleGenerateContentParams(model, context, options ?? {});
+			// `model.baseUrl` already includes the API version segment when set (mirrors the
+			// `apiVersion: ""` reset that the SDK relied on for custom base URLs).
+			const base = model.baseUrl?.trim() || DEFAULT_GENERATIVE_LANGUAGE_BASE;
+			const url = `${base}/models/${model.id}:streamGenerateContent?alt=sse`;
+			const headers: Record<string, string> = {
+				"x-goog-api-key": apiKey,
+				...(model.headers ?? {}),
+				...(options?.headers ?? {}),
+			};
+			return { params, url, headers, fetch: options?.fetch };
+		},
+	});
+};

package/src/providers/grammar.ts

@@ -0,0 +1,70 @@
+export function compactGrammarDefinition(syntax: "lark" | "regex", definition: string): string {
+	if (syntax !== "lark") {
+		return definition;
+	}
+
+	return compactLarkGrammarDefinition(definition);
+}
+
+function compactLarkGrammarDefinition(definition: string): string {
+	const lines: string[] = [];
+
+	for (const line of definition.split(/\r?\n/)) {
+		const uncommented = stripLarkLineComment(line).trimEnd();
+		if (uncommented.trim()) {
+			lines.push(uncommented);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function stripLarkLineComment(line: string): string {
+	let inString: string | undefined;
+	let inRegex = false;
+	let escaped = false;
+
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		const next = line[i + 1];
+
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+
+		if (inString) {
+			if (char === inString) {
+				inString = undefined;
+			}
+			continue;
+		}
+
+		if (inRegex) {
+			if (char === "/") {
+				inRegex = false;
+			}
+			continue;
+		}
+
+		if (char === "/" && next === "/") {
+			return line.slice(0, i);
+		}
+
+		if (char === '"' || char === "'") {
+			inString = char;
+			continue;
+		}
+
+		if (char === "/") {
+			inRegex = true;
+		}
+	}
+
+	return line;
+}

package/src/providers/kimi.ts

@@ -0,0 +1,51 @@
+/**
+ * Kimi Code provider - wraps OpenAI or Anthropic API based on format setting.
+ *
+ * Kimi offers both OpenAI-compatible and Anthropic-compatible APIs:
+ * - OpenAI: https://api.kimi.com/coding/v1/chat/completions
+ * - Anthropic: https://api.kimi.com/coding/v1/messages
+ *
+ * Each discovered model selects its server-declared protocol; legacy models
+ * without protocol metadata retain the Anthropic-compatible default.
+ */
+
+import { getKimiCommonHeaders } from "../registry/oauth/kimi";
+import type { Api, Context, Model } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import {
+	type OpenAIAnthropicApiFormat,
+	type OpenAIAnthropicShimOptions,
+	streamOpenAIAnthropicShim,
+} from "./openai-anthropic-shim";
+
+export type KimiApiFormat = OpenAIAnthropicApiFormat;
+
+export interface KimiOptions extends OpenAIAnthropicShimOptions {
+	/** Explicit API format override. Defaults to the model's discovered protocol. */
+	format?: KimiApiFormat;
+}
+
+/**
+ * Stream from Kimi Code, routing to either OpenAI or Anthropic API based on format.
+ * Returns synchronously like other providers - async header fetching happens internally.
+ */
+export function streamKimi(
+	model: Model<"openai-completions">,
+	context: Context,
+	options?: KimiOptions,
+): AssistantMessageEventStream {
+	return streamOpenAIAnthropicShim(model, context, options, {
+		anthropicBaseUrl: model.baseUrl.replace(/\/v1\/?$/, ""),
+		defaultFormat: model.compat.kimiApiFormat ?? "anthropic",
+		anthropicThinkingMode: model.compat.thinkingFormat === "kimi" ? "anthropic-adaptive" : undefined,
+		forwardCacheOptions: true,
+		extraHeaders: getKimiCommonHeaders,
+	});
+}
+
+/**
+ * Check if a model is a Kimi Code model.
+ */
+export function isKimiModel(model: Model<Api>): boolean {
+	return model.provider === "kimi-code";
+}