@oh-my-pi/pi-ai 18.2.7 → 18.2.8

package/src/providers/video-server.ts

@@ -0,0 +1,286 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type {
+	VideoAspectRatio,
+	VideoFrameImage,
+	VideoGenerationRequest,
+	VideoInputReference,
+	VideoJob,
+	VideoResolution,
+} from "../video/types";
+
+const submitRequestSchema = type({
+	model: "string > 0",
+	"prompt?": "unknown",
+	"duration?": "unknown",
+	"resolution?": "unknown",
+	"aspect_ratio?": "unknown",
+	"size?": "unknown",
+	"frame_images?": "unknown",
+	"input_references?": "unknown",
+	"generate_audio?": "unknown",
+	"seed?": "unknown",
+	"callback_url?": "unknown",
+	"provider?": "unknown",
+	"previous_job_id?": "unknown",
+	"session_id?": "unknown",
+	"trace?": "unknown",
+	"user?": "unknown",
+	"creativity?": "unknown",
+	"upscale_factor?": "unknown",
+});
+
+const gatewayJobIdSchema = type({ provider: "string > 0", modelId: "string > 0", upstreamId: "string > 0" });
+
+const VIDEO_RESOLUTIONS: readonly VideoResolution[] = ["360p", "480p", "720p", "768p", "1080p", "1K", "2K", "4K"];
+const VIDEO_ASPECT_RATIOS: readonly VideoAspectRatio[] = [
+	"16:9",
+	"9:16",
+	"1:1",
+	"4:3",
+	"3:4",
+	"3:2",
+	"2:3",
+	"21:9",
+	"9:21",
+];
+
+export class VideoWireError extends AIError.ValidationError {
+	readonly status: number;
+
+	constructor(status: number, message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "VideoWireError";
+		this.status = status;
+	}
+}
+
+export interface VideoParsedRequest {
+	modelId: string;
+	request: VideoGenerationRequest;
+}
+
+export interface GatewayJobIdentity {
+	provider: string;
+	modelId: string;
+	upstreamId: string;
+}
+
+function invalid(message: string): never {
+	throw new VideoWireError(400, `videos: ${message}`);
+}
+
+function optionalString(value: unknown, field: string, maxLength?: number): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || value.length === 0) invalid(`${field} must be a non-empty string`);
+	if (maxLength !== undefined && value.length > maxLength) invalid(`${field} must not exceed ${maxLength} characters`);
+	return value;
+}
+
+function optionalRecord(value: unknown, field: string): Record<string, unknown> | undefined {
+	if (value === undefined) return undefined;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) invalid(`${field} must be an object`);
+	return value as Record<string, unknown>;
+}
+
+function optionalInteger(value: unknown, field: string, minimum?: number): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isInteger(value) || (minimum !== undefined && value < minimum)) {
+		invalid(`${field} must be ${minimum === undefined ? "an integer" : `an integer >= ${minimum}`}`);
+	}
+	return value;
+}
+
+function optionalNumber(value: unknown, field: string, exclusiveMinimum?: number): number | undefined {
+	if (value === undefined) return undefined;
+	if (
+		typeof value !== "number" ||
+		!Number.isFinite(value) ||
+		(exclusiveMinimum !== undefined && value <= exclusiveMinimum)
+	) {
+		invalid(`${field} must be a finite number${exclusiveMinimum === undefined ? "" : ` > ${exclusiveMinimum}`}`);
+	}
+	return value;
+}
+
+function optionalBoolean(value: unknown, field: string): boolean | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "boolean") invalid(`${field} must be a boolean`);
+	return value;
+}
+
+function assetUrl(value: unknown, field: string): { url: string } {
+	const record = optionalRecord(value, field);
+	const url = optionalString(record?.url, `${field}.url`);
+	if (!url) invalid(`${field}.url must be a non-empty string`);
+	return { url };
+}
+
+function parseFrameImages(value: unknown): VideoFrameImage[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) invalid("frame_images must be an array");
+	return value.map((entry, index) => {
+		const record = optionalRecord(entry, `frame_images[${index}]`)!;
+		if (record.type !== "image_url") invalid(`frame_images[${index}].type must be image_url`);
+		if (record.frame_type !== "first_frame" && record.frame_type !== "last_frame") {
+			invalid(`frame_images[${index}].frame_type must be first_frame or last_frame`);
+		}
+		return {
+			type: "image_url",
+			imageUrl: assetUrl(record.image_url, `frame_images[${index}].image_url`),
+			frameType: record.frame_type,
+		};
+	});
+}
+
+function parseInputReferences(value: unknown): VideoInputReference[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) invalid("input_references must be an array");
+	return value.map((entry, index) => {
+		const record = optionalRecord(entry, `input_references[${index}]`)!;
+		switch (record.type) {
+			case "image_url":
+				return {
+					type: "image_url",
+					imageUrl: assetUrl(record.image_url, `input_references[${index}].image_url`),
+				};
+			case "audio_url":
+				return {
+					type: "audio_url",
+					audioUrl: assetUrl(record.audio_url, `input_references[${index}].audio_url`),
+				};
+			case "video_url":
+				return {
+					type: "video_url",
+					videoUrl: assetUrl(record.video_url, `input_references[${index}].video_url`),
+				};
+			default:
+				return invalid(`input_references[${index}].type must be image_url, audio_url, or video_url`);
+		}
+	});
+}
+
+/** Parse and validate an OpenRouter-compatible video submit body. */
+export function parseRequest(body: unknown): VideoParsedRequest {
+	const parsed = submitRequestSchema(body);
+	if (parsed instanceof type.errors) invalid(parsed.summary);
+	const prompt = optionalString(parsed.prompt, "prompt");
+	const duration = optionalInteger(parsed.duration, "duration", 1);
+	const resolution = optionalString(parsed.resolution, "resolution");
+	if (resolution !== undefined && !VIDEO_RESOLUTIONS.includes(resolution as VideoResolution)) {
+		invalid(`resolution must be one of ${VIDEO_RESOLUTIONS.join(", ")}`);
+	}
+	const aspectRatio = optionalString(parsed.aspect_ratio, "aspect_ratio");
+	if (aspectRatio !== undefined && !VIDEO_ASPECT_RATIOS.includes(aspectRatio as VideoAspectRatio)) {
+		invalid(`aspect_ratio must be one of ${VIDEO_ASPECT_RATIOS.join(", ")}`);
+	}
+	const callbackUrl = optionalString(parsed.callback_url, "callback_url");
+	if (callbackUrl !== undefined) {
+		let url: URL;
+		try {
+			url = new URL(callbackUrl);
+		} catch (error) {
+			throw new VideoWireError(400, "videos: callback_url must be a valid HTTPS URL", { cause: error });
+		}
+		if (url.protocol !== "https:") invalid("callback_url must be a valid HTTPS URL");
+	}
+	const provider = optionalRecord(parsed.provider, "provider");
+	const providerOptions = optionalRecord(provider?.options, "provider.options");
+	const previousJobId = optionalString(parsed.previous_job_id, "previous_job_id");
+	const sessionId = optionalString(parsed.session_id, "session_id", 256);
+	const user = optionalString(parsed.user, "user", 256);
+	const size = optionalString(parsed.size, "size");
+	const frameImages = parseFrameImages(parsed.frame_images);
+	const inputReferences = parseInputReferences(parsed.input_references);
+	const generateAudio = optionalBoolean(parsed.generate_audio, "generate_audio");
+	const seed = optionalInteger(parsed.seed, "seed");
+	const trace = optionalRecord(parsed.trace, "trace");
+	const creativity = optionalInteger(parsed.creativity, "creativity");
+	const upscaleFactor = optionalNumber(parsed.upscale_factor, "upscale_factor", 0);
+	return {
+		modelId: parsed.model,
+		request: {
+			...(prompt !== undefined && { prompt }),
+			...(duration !== undefined && { duration }),
+			...(resolution !== undefined && { resolution: resolution as VideoResolution }),
+			...(aspectRatio !== undefined && { aspectRatio: aspectRatio as VideoAspectRatio }),
+			...(size !== undefined && { size }),
+			...(frameImages !== undefined && { frameImages }),
+			...(inputReferences !== undefined && { inputReferences }),
+			...(generateAudio !== undefined && { generateAudio }),
+			...(seed !== undefined && { seed }),
+			...(callbackUrl !== undefined && { callbackUrl }),
+			...(provider !== undefined && { provider: providerOptions === undefined ? {} : { options: providerOptions } }),
+			...(previousJobId !== undefined && { previousJobId }),
+			...(sessionId !== undefined && { sessionId }),
+			...(trace !== undefined && { trace }),
+			...(user !== undefined && { user }),
+			...(creativity !== undefined && { creativity }),
+			...(upscaleFactor !== undefined && { upscaleFactor }),
+		},
+	};
+}
+
+/** Encode all provider/model routing needed to resolve a future poll without gateway state. */
+export function encodeGatewayJobId(identity: GatewayJobIdentity): string {
+	return new TextEncoder().encode(JSON.stringify(identity)).toBase64({ alphabet: "base64url", omitPadding: true });
+}
+
+/** Decode a stateless gateway job id, rejecting malformed or incomplete identities. */
+export function decodeGatewayJobId(id: string): GatewayJobIdentity {
+	try {
+		const json = new TextDecoder().decode(Uint8Array.fromBase64(id, { alphabet: "base64url" }));
+		const parsed = gatewayJobIdSchema(JSON.parse(json));
+		if (parsed instanceof type.errors) invalid("invalid video job id");
+		return parsed;
+	} catch (error) {
+		if (error instanceof VideoWireError) throw error;
+		throw new VideoWireError(400, "videos: invalid video job id", { cause: error });
+	}
+}
+
+function gatewayUrls(req: Request, gatewayId: string): { pollingUrl: string; contentUrl: string } {
+	const origin = new URL(req.url).origin;
+	const root = `${origin}/v1/videos/${encodeURIComponent(gatewayId)}`;
+	return { pollingUrl: root, contentUrl: `${root}/content` };
+}
+
+export interface VideoResponseBody {
+	id: string;
+	status: VideoJob["status"];
+	polling_url: string;
+	generation_id?: string;
+	unsigned_urls?: string[];
+	error?: string;
+	usage?: { cost: number };
+}
+
+function encodeJobResponse(job: VideoJob, req: Request, gatewayId: string): VideoResponseBody {
+	const urls = gatewayUrls(req, gatewayId);
+	return {
+		id: gatewayId,
+		status: job.status,
+		polling_url: urls.pollingUrl,
+		...(job.generationId !== undefined && { generation_id: job.generationId }),
+		...(job.contentUrls !== undefined && { unsigned_urls: job.contentUrls.map(() => urls.contentUrl) }),
+		...(job.error !== undefined && { error: job.error }),
+		...(job.usage !== undefined && { usage: { cost: job.usage.cost.total } }),
+	};
+}
+
+/** Rewrite a provider submit response so every future operation returns through this gateway. */
+export function encodeSubmitResponse(job: VideoJob, req: Request, gatewayId: string): VideoResponseBody {
+	return encodeJobResponse(job, req, gatewayId);
+}
+
+/** Rewrite a provider poll response so content URLs and polling stay on this gateway. */
+export function encodePollResponse(job: VideoJob, req: Request, gatewayId: string): VideoResponseBody {
+	return encodeJobResponse(job, req, gatewayId);
+}
+
+export function formatError(status: number, errorType: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { code: status, type: errorType, message } }), {
+		status,
+		headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
+	});
+}

package/src/rerank/index.ts

@@ -0,0 +1,13 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { rerankOpenRouter, type RerankOptions } from "./openrouter-rerank";
+import type { RerankRequest, RerankResult } from "./types";
+
+export * from "./openrouter-rerank";
+export * from "./types";
+
+/** Dispatch reranking through the transport selected by the catalog model. */
+export function rerank(model: Model<Api>, request: RerankRequest, options: RerankOptions): Promise<RerankResult> {
+	if (model.api === "openrouter-rerank") return rerankOpenRouter(model, request, options);
+	throw new AIError.ConfigurationError(`Unsupported rerank API: ${model.api}`);
+}

package/src/rerank/openrouter-rerank.ts

@@ -0,0 +1,136 @@
+import { type } from "@oh-my-pi/omptype";
+import { calculateCost } from "@oh-my-pi/pi-catalog/models";
+import type { Api, FetchImpl, Model, Usage } from "@oh-my-pi/pi-catalog/types";
+import { type ApiKey, withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import type { RerankRequest, RerankResult } from "./types";
+
+export interface RerankOptions {
+	apiKey: ApiKey;
+	fetch?: FetchImpl;
+	signal?: AbortSignal;
+}
+
+/** Non-2xx response from an OpenRouter-compatible rerank endpoint. */
+export class RerankApiError extends AIError.ProviderHttpError {
+	override readonly name = "RerankApiError";
+}
+
+const upstreamResponseSchema = type({
+	model: "string",
+	results: type({
+		index: "number",
+		relevance_score: "number",
+		"document?": "unknown",
+	}).array(),
+	"usage?": "object",
+});
+
+interface UpstreamUsage {
+	total_tokens?: unknown;
+	cost?: unknown;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function decodeUsage(model: Model<Api>, raw: unknown): Usage {
+	const upstream = raw && typeof raw === "object" ? (raw as UpstreamUsage) : {};
+	const totalTokens = finiteNumber(upstream.total_tokens) ?? 0;
+	const reportedCost = finiteNumber(upstream.cost);
+	const usage: Usage = {
+		input: totalTokens,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: reportedCost ?? 0 },
+	};
+	if (reportedCost === undefined) calculateCost(model, usage);
+	return usage;
+}
+
+function documentText(document: unknown): string | undefined {
+	if (typeof document === "string") return document;
+	if (document === null || typeof document !== "object" || !("text" in document)) return undefined;
+	return typeof document.text === "string" ? document.text : undefined;
+}
+
+async function responseError(response: Response, model: Model<Api>): Promise<RerankApiError> {
+	const text = await response.text();
+	let detail = text;
+	let code: string | undefined;
+	try {
+		const parsed: unknown = JSON.parse(text);
+		if (parsed && typeof parsed === "object" && "error" in parsed) {
+			const error = parsed.error;
+			if (error && typeof error === "object") {
+				const envelope = error as { message?: unknown; code?: unknown; type?: unknown };
+				if (typeof envelope.message === "string") detail = envelope.message;
+				if (typeof envelope.code === "string" || typeof envelope.code === "number") code = String(envelope.code);
+				else if (typeof envelope.type === "string") code = envelope.type;
+			}
+		}
+	} catch {}
+	return new RerankApiError(
+		`${model.provider}/${model.id} rerank API error (${response.status}): ${detail || response.statusText}`,
+		response.status,
+		{ headers: response.headers, code },
+	);
+}
+
+/** Call an OpenRouter-compatible rerank endpoint. */
+export async function rerankOpenRouter(
+	model: Model<Api>,
+	request: RerankRequest,
+	options: RerankOptions,
+): Promise<RerankResult> {
+	const body = JSON.stringify({
+		model: model.id,
+		query: request.query,
+		documents: request.documents,
+		...(request.topN !== undefined && { top_n: request.topN }),
+		...(request.returnDocuments !== undefined && { return_documents: request.returnDocuments }),
+	});
+	const fetchImpl = options.fetch ?? fetch;
+	const response = await withAuth(
+		options.apiKey,
+		async key => {
+			const attempt = await fetchImpl(`${model.baseUrl.replace(/\/+$/, "")}/rerank`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${key}`,
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body,
+				signal: options.signal,
+			});
+			if (!attempt.ok) throw await responseError(attempt, model);
+			return attempt;
+		},
+		{ signal: options.signal },
+	);
+
+	const payload: unknown = await response.json();
+	const parsed = upstreamResponseSchema(payload);
+	if (parsed instanceof type.errors) {
+		throw new AIError.ProviderResponseError(
+			`${model.provider}/${model.id} rerank response is malformed: ${parsed.summary}`,
+			{ provider: model.provider, kind: "envelope" },
+		);
+	}
+	return {
+		model: parsed.model,
+		results: parsed.results.map(result => {
+			const document = documentText(result.document);
+			return {
+				index: result.index,
+				relevanceScore: result.relevance_score,
+				...(document !== undefined && { document }),
+			};
+		}),
+		usage: decodeUsage(model, parsed.usage),
+	};
+}

package/src/rerank/types.ts

@@ -0,0 +1,20 @@
+import type { Usage } from "@oh-my-pi/pi-catalog/types";
+
+export interface RerankRequest {
+	query: string;
+	documents: string[];
+	topN?: number;
+	returnDocuments?: boolean;
+}
+
+export interface RerankResultItem {
+	index: number;
+	relevanceScore: number;
+	document?: string;
+}
+
+export interface RerankResult {
+	results: RerankResultItem[];
+	model: string;
+	usage: Usage;
+}

package/src/speech/index.ts

@@ -0,0 +1,35 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { synthesizeOpenAiSpeech } from "./openai-speech";
+import type { SpeechOptions, SpeechRequest, SpeechResult } from "./types";
+import { synthesizeXaiSpeech } from "./xai-tts";
+
+export * from "./openai-speech";
+export * from "./transport";
+export * from "./types";
+export * from "./xai-tts";
+
+/** Catalog APIs {@link synthesizeSpeech} serves; the `tts` tool and the gateway gate on these. */
+export const SPEECH_APIS = ["xai-tts", "openai-speech"] as const;
+export type SpeechApi = (typeof SPEECH_APIS)[number];
+
+/** Whether a catalog API synthesizes speech through a cloud transport (local inference is tool-only). */
+export function isSpeechApi(api: Api): api is SpeechApi {
+	return api === "xai-tts" || api === "openai-speech";
+}
+
+/** Synthesize speech through the transport selected by the catalog model's `api`. */
+export function synthesizeSpeech(
+	model: Model<Api>,
+	request: SpeechRequest,
+	options: SpeechOptions,
+): Promise<SpeechResult> {
+	switch (model.api) {
+		case "xai-tts":
+			return synthesizeXaiSpeech(model, request, options);
+		case "openai-speech":
+			return synthesizeOpenAiSpeech(model, request, options);
+		default:
+			throw new AIError.ConfigurationError(`Unsupported speech API: ${model.api}`);
+	}
+}

package/src/speech/openai-speech.ts

@@ -0,0 +1,26 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { postSpeechRequest } from "./transport";
+import type { SpeechOptions, SpeechRequest, SpeechResult } from "./types";
+
+export async function synthesizeOpenAiSpeech(
+	model: Model<Api>,
+	request: SpeechRequest,
+	options: SpeechOptions,
+): Promise<SpeechResult> {
+	if (request.sampleRate !== undefined) {
+		throw new AIError.ValidationError("openai-speech does not support sampleRate");
+	}
+	if (request.bitRate !== undefined) {
+		throw new AIError.ValidationError("openai-speech does not support bitRate");
+	}
+	const payload: Record<string, unknown> = {
+		model: model.id,
+		input: request.text,
+		response_format: request.format,
+		...(request.voice !== undefined ? { voice: request.voice } : {}),
+		...(request.speed !== undefined ? { speed: request.speed } : {}),
+		...(request.instructions !== undefined ? { instructions: request.instructions } : {}),
+	};
+	return postSpeechRequest(model, "/audio/speech", payload, request.format, options);
+}

package/src/speech/transport.ts

@@ -0,0 +1,66 @@
+import { calculateCost } from "@oh-my-pi/pi-catalog/models";
+import type { Api, Model, Usage } from "@oh-my-pi/pi-catalog/types";
+import { USER_AGENT } from "@oh-my-pi/pi-utils";
+import { withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import { SPEECH_FORMAT_MIME_TYPES, type SpeechFormat, type SpeechOptions, type SpeechResult } from "./types";
+
+const SPEECH_TIMEOUT_MS = 60_000;
+
+export class SpeechApiError extends AIError.ProviderHttpError {
+	override readonly name = "SpeechApiError";
+}
+
+export async function postSpeechRequest(
+	model: Model<Api>,
+	path: string,
+	payload: Record<string, unknown>,
+	format: SpeechFormat,
+	options: SpeechOptions,
+): Promise<SpeechResult> {
+	const timeoutSignal = AbortSignal.timeout(SPEECH_TIMEOUT_MS);
+	const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+	const fetchImpl = options.fetch ?? fetch;
+	const label = `${model.provider}/${model.id}`;
+	const audio = await withAuth(
+		options.apiKey,
+		async key => {
+			const configuredHeaders = model.resolveHeaders ? await model.resolveHeaders(signal) : model.headers;
+			const response = await fetchImpl(`${model.baseUrl.replace(/\/+$/, "")}${path}`, {
+				method: "POST",
+				headers: {
+					...configuredHeaders,
+					Authorization: `Bearer ${key}`,
+					"Content-Type": "application/json",
+					"User-Agent": USER_AGENT,
+				},
+				body: JSON.stringify(payload),
+				signal,
+			});
+			if (!response.ok) {
+				const detail = await response.text();
+				throw new SpeechApiError(
+					`${label} speech API failed (${response.status}): ${detail.slice(0, 300)}`,
+					response.status,
+					{
+						headers: response.headers,
+					},
+				);
+			}
+			return new Uint8Array(await response.arrayBuffer());
+		},
+		{ signal },
+	);
+	// Speech endpoints return only audio bytes. OpenRouter exposes a generation id,
+	// but neither it nor the OpenAI/xAI wires report token or billable-unit usage.
+	const usage: Usage = {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+	calculateCost(model, usage);
+	return { audio, mimeType: SPEECH_FORMAT_MIME_TYPES[format], usage };
+}

package/src/speech/types.ts

@@ -0,0 +1,37 @@
+import type { FetchImpl, Usage } from "@oh-my-pi/pi-catalog/types";
+import type { ApiKey } from "../auth-retry";
+
+export const SPEECH_FORMATS = ["mp3", "wav", "pcm", "opus", "aac", "flac"] as const;
+
+export type SpeechFormat = (typeof SPEECH_FORMATS)[number];
+
+export const SPEECH_FORMAT_MIME_TYPES: Record<SpeechFormat, string> = {
+	mp3: "audio/mpeg",
+	wav: "audio/wav",
+	pcm: "audio/pcm",
+	opus: "audio/opus",
+	aac: "audio/aac",
+	flac: "audio/flac",
+};
+
+export interface SpeechRequest {
+	text: string;
+	voice?: string;
+	format: SpeechFormat;
+	speed?: number;
+	sampleRate?: number;
+	bitRate?: number;
+	instructions?: string;
+}
+
+export interface SpeechResult {
+	audio: Uint8Array;
+	mimeType: string;
+	usage: Usage;
+}
+
+export interface SpeechOptions {
+	apiKey: ApiKey;
+	fetch?: FetchImpl;
+	signal?: AbortSignal;
+}

package/src/speech/xai-tts.ts

@@ -0,0 +1,41 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { postSpeechRequest } from "./transport";
+import type { SpeechOptions, SpeechRequest, SpeechResult } from "./types";
+
+export const DEFAULT_XAI_VOICE_ID = "eve";
+export const DEFAULT_XAI_SAMPLE_RATE = 24_000;
+export const DEFAULT_XAI_BIT_RATE = 128_000;
+export const XAI_MAX_TEXT_LENGTH = 15_000;
+
+export async function synthesizeXaiSpeech(
+	model: Model<Api>,
+	request: SpeechRequest,
+	options: SpeechOptions,
+): Promise<SpeechResult> {
+	if (request.text.length > XAI_MAX_TEXT_LENGTH) {
+		throw new AIError.ValidationError(`xai-tts input exceeds the ${XAI_MAX_TEXT_LENGTH}-character limit`);
+	}
+	if (request.format !== "mp3" && request.format !== "wav") {
+		throw new AIError.ValidationError(`xai-tts does not support ${request.format} output; use mp3 or wav`);
+	}
+	if (request.speed !== undefined) throw new AIError.ValidationError("xai-tts does not support speed");
+	if (request.instructions !== undefined) throw new AIError.ValidationError("xai-tts does not support instructions");
+
+	const sampleRate = request.sampleRate ?? DEFAULT_XAI_SAMPLE_RATE;
+	const bitRate = request.bitRate ?? DEFAULT_XAI_BIT_RATE;
+	const payload: Record<string, unknown> = {
+		text: request.text,
+		voice_id: request.voice ?? DEFAULT_XAI_VOICE_ID,
+	};
+	const codecOverridden = request.format !== "mp3";
+	const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
+	const bitRateOverridden = request.format === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
+	if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
+		const outputFormat: Record<string, unknown> = { codec: request.format };
+		if (sampleRate > 0) outputFormat.sample_rate = sampleRate;
+		if (request.format === "mp3" && bitRate > 0) outputFormat.bit_rate = bitRate;
+		payload.output_format = outputFormat;
+	}
+	return postSpeechRequest(model, "/tts", payload, request.format, options);
+}

package/src/transcription/index.ts

@@ -0,0 +1,17 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { transcribeOpenAI, type TranscriptionOptions } from "./openai-transcriptions";
+import type { TranscriptionRequest, TranscriptionResult } from "./types";
+
+export * from "./openai-transcriptions";
+export * from "./types";
+
+/** Dispatch an audio transcription through the transport selected by the catalog model. */
+export function transcribeAudio(
+	model: Model<Api>,
+	request: TranscriptionRequest,
+	options: TranscriptionOptions,
+): Promise<TranscriptionResult> {
+	if (model.api === "openai-transcriptions") return transcribeOpenAI(model, request, options);
+	throw new AIError.ConfigurationError(`Unsupported transcription API: ${model.api}`);
+}