@gtrabanco/pi-nan-provider 0.2.1

package/src/fetch-models.ts

@@ -0,0 +1,254 @@
+/**
+ * Runtime model catalog for NaN-compatible providers.
+ *
+ * Two layers, never either alone:
+ *
+ *  1. Build-time generated fallback — `scripts/models.generated.ts`, committed
+ *     to the repo and regenerated pre-publish by `scripts/generate-models.ts`
+ *     from models.dev. Every capability number in it traces to its source.
+ *
+ *  2. Runtime fetch of the provider's own `/models` endpoint. NaN runs
+ *     LiteLLM behind an OpenAI-compatible facade, so the response carries
+ *     only model `id`s — no capability fields. It is used solely to confirm
+ *     which model IDs are currently live.
+ *
+ * Merge: live IDs × generated capability data. A live ID with no generated
+ * match is kept with conservative placeholder limits (the same defaults used
+ * in custom-provider.md's dynamic-discovery example) and no reasoning
+ * support — capabilities stay "unknown", nothing is fabricated. On fetch
+ * failure, timeout, or an unusable response, callers fall back to the
+ * generated catalog so startup is never blocked.
+ */
+
+import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
+import { GENERATED_CATALOG_META, NAN_GENERATED_MODELS } from "../scripts/models.generated.ts";
+
+export type { Model };
+
+/**
+ * Serializable model definition in the generated fallback catalog
+ * (scripts/models.generated.ts). Lives here so the generator (scripts/) and
+ * the runtime share one definition without a circular type alias.
+ */
+export interface GeneratedModelEntry {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow: number;
+	maxTokens: number;
+	/** Compat applied to every NaN-compatible model (LiteLLM-confirmed, see scripts/generate-models.ts). */
+	compat?: OpenAICompletionsCompat;
+	/** Provenance notes for values overriding models.dev or needing manual confirmation. */
+	notes?: string[];
+	/**
+	 * Raw models.dev model object (provider `nan`) preserved verbatim so every
+	 * documented property survives generation — quotas, tiers, release dates,
+	 * reasoning options, attachment flags, etc. Informational only.
+	 */
+	extras?: Record<string, unknown>;
+}
+
+/** pi-ai streaming API used for every NaN-compatible provider. */
+export const NAN_COMPAT_API = "openai-completions" as const;
+
+/**
+ * Conservative limits for live IDs with no generated capability match.
+ * Mirrors the `?? 128000` / `?? 4096` defaults in custom-provider.md's
+ * dynamic-discovery example: a safe request envelope, not a capability claim.
+ */
+export const UNKNOWN_MODEL_LIMITS = { contextWindow: 128_000, maxTokens: 4_096 } as const;
+
+/** Timeout for the live /models fetch; matches the pi-synthetic-provider precedent (~3s). */
+export const DEFAULT_MODELS_TIMEOUT_MS = 3_000;
+
+export interface CatalogSource {
+	/** Provider id as registered in pi, e.g. "nan". */
+	providerId: string;
+	/** OpenAI-compatible base URL including version path, e.g. "https://api.nan.builders/v1". */
+	baseUrl: string;
+}
+
+/** Convert a generated catalog entry into a pi-ai Model for the given provider. */
+export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Model<"openai-completions"> {
+	return {
+		id: entry.id,
+		name: entry.name,
+		api: NAN_COMPAT_API,
+		provider: source.providerId,
+		baseUrl: source.baseUrl,
+		reasoning: entry.reasoning,
+		input: [...entry.input],
+		cost: { ...entry.cost },
+		contextWindow: entry.contextWindow,
+		maxTokens: entry.maxTokens,
+		...(entry.compat ? { compat: { ...entry.compat } } : {}),
+	};
+}
+
+/** The generated fallback catalog as pi-ai Models for the given provider. */
+export function baselineModels(source: CatalogSource): Model<"openai-completions">[] {
+	return NAN_GENERATED_MODELS.map((entry) => toModel(entry, source));
+}
+
+export interface LiveModelListOptions {
+	baseUrl: string;
+	/** Optional bearer key. NaN's /models returns 401 without one. */
+	apiKey?: string;
+	timeoutMs?: number;
+	/** Injectable for tests; defaults to global fetch. */
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * Fetch live model IDs from `{baseUrl}/models`.
+ *
+ * Returns `undefined` on any failure — non-OK status, timeout, malformed or
+ * empty body — so callers fall back to the generated catalog instead of
+ * failing startup. IDs are trimmed, de-duplicated, and order-preserving.
+ */
+export async function listLiveModelIds(options: LiveModelListOptions): Promise<string[] | undefined> {
+	const { baseUrl, apiKey, timeoutMs = DEFAULT_MODELS_TIMEOUT_MS, fetchImpl = fetch } = options;
+
+	const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+	const headers: Record<string, string> = { Accept: "application/json" };
+	if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetchImpl(url, { headers, signal: controller.signal });
+		if (!response.ok) return undefined;
+
+		const payload = (await response.json()) as { data?: Array<{ id?: unknown }> };
+		const rows = payload?.data;
+		if (!Array.isArray(rows)) return undefined;
+
+		const ids = rows
+			.map((row) => (typeof row?.id === "string" ? row.id.trim() : ""))
+			.filter((id) => id.length > 0);
+		// An empty live list is indistinguishable from "endpoint unusable":
+		// prefer the generated catalog over an empty registration.
+		return ids.length > 0 ? [...new Set(ids)] : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+
+export interface MergedCatalog {
+	models: Model<"openai-completions">[];
+	/** Live IDs resolved against generated capability data. */
+	matched: string[];
+	/** Live IDs kept with unknown capabilities (conservative limits). */
+	unknown: string[];
+}
+
+/**
+ * Merge live model IDs with the generated capability catalog.
+ * Known IDs get generated data; unknown IDs get conservative placeholder
+ * limits, `reasoning: false`, and zero cost — documented defaults, not
+ * invented capabilities.
+ */
+export function mergeLiveWithGenerated(
+	liveIds: readonly string[],
+	source: CatalogSource,
+	generated: readonly GeneratedModelEntry[] = NAN_GENERATED_MODELS,
+): MergedCatalog {
+	const byId = new Map(generated.map((entry) => [entry.id, entry]));
+	const models: Model<"openai-completions">[] = [];
+	const matched: string[] = [];
+	const unknown: string[] = [];
+
+	for (const id of liveIds) {
+		const entry = byId.get(id);
+		if (entry) {
+			models.push(toModel(entry, source));
+			matched.push(id);
+		} else {
+			models.push({
+				id,
+				name: id,
+				api: NAN_COMPAT_API,
+				provider: source.providerId,
+				baseUrl: source.baseUrl,
+				reasoning: false,
+				input: ["text"],
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: UNKNOWN_MODEL_LIMITS.contextWindow,
+				maxTokens: UNKNOWN_MODEL_LIMITS.maxTokens,
+			});
+			unknown.push(id);
+		}
+	}
+
+	return { models, matched, unknown };
+}
+
+export interface FetchModelsOptions {
+	/** Bearer key for the live fetch, when one is already resolved. */
+	apiKey?: string;
+	timeoutMs?: number;
+	/** Injectable for tests; defaults to global fetch. */
+	fetchImpl?: typeof fetch;
+}
+
+export interface ResolvedCatalog {
+	/** Live IDs × generated capability data; the generated catalog when live fetch fails. */
+	models: Model<"openai-completions">[];
+	/**
+	 * Live model IDs from the provider's /models endpoint when the fetch
+	 * succeeded — the authoritative per-key list (what your NaN membership can
+	 * actually use, e.g. premium-tier models included/excluded). `undefined`
+	 * when the live fetch failed and the generated fallback was used.
+	 */
+	liveIds: Set<string> | undefined;
+	/** Live IDs kept with unknown capabilities (present only when liveIds is set). */
+	unknownIds: string[];
+}
+
+/**
+ * Resolve the effective catalog: live `/models` IDs × generated capability
+ * data. A successful live fetch is authoritative (tier-aware: it reflects
+ * exactly what your NaN key can use); failure degrades to the generated
+ * fallback so startup is never blocked.
+ */
+export async function resolveCatalog(
+	source: CatalogSource,
+	options: FetchModelsOptions = {},
+): Promise<ResolvedCatalog> {
+	const baseline = baselineModels(source);
+	try {
+		const liveIds = await listLiveModelIds({
+			baseUrl: source.baseUrl,
+			apiKey: options.apiKey,
+			timeoutMs: options.timeoutMs,
+			fetchImpl: options.fetchImpl,
+		});
+		if (!liveIds) return { models: baseline, liveIds: undefined, unknownIds: [] };
+		const merged = mergeLiveWithGenerated(liveIds, source);
+		return { models: merged.models, liveIds: new Set(liveIds), unknownIds: merged.unknown };
+	} catch {
+		return { models: baseline, liveIds: undefined, unknownIds: [] };
+	}
+}
+
+/**
+ * `fetchModels` implementation handed to pi-ai's `createProvider`: live IDs ×
+ * generated capability data, falling back to the generated catalog whenever
+ * the live endpoint is unreachable, slow, non-OK, malformed, or empty —
+ * startup is never blocked by the catalog fetch.
+ */
+export async function fetchNanCompatibleModels(
+	source: CatalogSource,
+	options: FetchModelsOptions = {},
+): Promise<readonly Model<"openai-completions">[]> {
+	return (await resolveCatalog(source, options)).models;
+}
+
+/** Metadata of the generated fallback catalog, for diagnostics and docs. */
+export function generatedCatalogMeta() {
+	return GENERATED_CATALOG_META;
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+/**
+ * @gtrabanco/pi-nan-provider — NaN Builders provider + MCP bridges for pi.
+ *
+ * What this extension registers:
+ *
+ *  1. Providers: every entry in PROVIDERS via the shared OpenAI-compatible
+ *     factory. The generated fallback catalog is available immediately at
+ *     startup; pi's Models runtime calls fetchModels (live /models ×
+ *     generated catalog) on network refreshes, and filterModels prunes the
+ *     models your key cannot actually use (tier detection). On pi versions
+ *     without the native Provider overload, registration falls back to the
+ *     legacy (name, config) form with the same baseline catalog.
+ *
+ *  2. MCP tools over pi's registerTool (pi intentionally has no MCP client):
+ *     - `nan_web_search` via NaN's official remote MCP server
+ *       (https://api.nan.builders/mcp) — on by default, NAN_MCP_TOOLS=0 to
+ *       disable.
+ *     - Media tools bridging the optional community `nan-mcp-server`
+ *       (stdio, spawned per call) — off by default, NAN_MEDIA_MCP=1 to
+ *       enable, so nothing runs unless audio/image/transcription is invoked.
+ */
+
+import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+import { baselineModels } from "./fetch-models.ts";
+import { createNanWebSearchTool, mcpToolsDisabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
+import { createNanMediaTools, mediaMcpEnabled } from "./mcp/nan-media.ts";
+import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
+import { PROVIDERS } from "./providers.ts";
+
+/**
+ * Register a provider on any pi version: the native full-Provider overload
+ * where supported, else the documented legacy (name, config) form with
+ * env-var auth. The fallback loses stored-credential auth (env only) — a
+ * documented limitation of the legacy path, never a silent auth invention.
+ */
+function registerProviderCompat(pi: ExtensionAPI, config: OpenAICompatibleProviderConfig): void {
+	const native = createNanCompatibleProvider(config);
+	try {
+		pi.registerProvider(native);
+		return;
+	} catch (error) {
+		console.warn(
+			`[pi-nan-provider] native provider registration rejected (${error instanceof Error ? error.message : String(error)}); ` +
+				"falling back to legacy config form (env-var auth only).",
+		);
+	}
+	const legacy: ProviderConfig = {
+		name: config.name,
+		baseUrl: config.baseUrl,
+		// Legacy config syntax: one env-var reference; first configured var wins.
+		...(config.envVars.length > 0 ? { apiKey: `$${config.envVars[0]}` } : {}),
+		api: "openai-completions",
+		models: baselineModels({ providerId: config.id, baseUrl: config.baseUrl }).map((model) => ({
+			id: model.id,
+			name: model.name,
+			reasoning: model.reasoning,
+			input: [...model.input],
+			cost: { ...model.cost },
+			contextWindow: model.contextWindow,
+			maxTokens: model.maxTokens,
+			...(model.compat ? { compat: { ...model.compat } } : {}),
+		})),
+	};
+	pi.registerProvider(config.id, legacy);
+}
+
+/**
+ * Register MCP-bridged tools when the runtime supports them. Old pi versions
+ * without registerTool simply skip this block — provider registration is
+ * unaffected.
+ */
+function registerMcpToolsCompat(pi: ExtensionAPI): void {
+	if (typeof pi.registerTool !== "function") return;
+	if (!mcpToolsDisabled()) {
+		pi.registerTool(createNanWebSearchTool());
+	}
+	if (mediaMcpEnabled()) {
+		for (const tool of createNanMediaTools()) {
+			pi.registerTool(tool);
+		}
+	}
+}
+
+export default function nanProviderExtension(pi: ExtensionAPI): void {
+	for (const config of PROVIDERS) {
+		registerProviderCompat(pi, config);
+	}
+	registerMcpToolsCompat(pi);
+}
+
+/** Exposed for tests: the env var this package uses for every NaN surface. */
+export { NAN_API_KEY_ENV };
+
+/** Exposed for advanced consumers that want the typed provider factory directly. */
+export { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
+export { PROVIDERS, NAN_PROVIDER } from "./providers.ts";

package/src/mcp/nan-media.ts

@@ -0,0 +1,199 @@
+/**
+ * Optional bridge to the community stdio MCP server
+ * `nan-mcp-server` (https://github.com/luciferfran/nan-mcp-server), which
+ * exposes NaN's media tools: image generation/editing (flux-2-klein), TTS
+ * (kokoro), STT (whisper), plus voice listing.
+ *
+ * Opt-in and fully lazy:
+ * - OFF by default. Enable with NAN_MEDIA_MCP=1.
+ * - The server process is spawned per tool call and terminated right after —
+ *   zero startup cost, nothing runs unless audio/image/transcription is
+ *   actually invoked.
+ * - NAN_API_KEY is forwarded to the child; NAN_OUTPUT_DIR and the server's
+ *   other env vars inherit from your environment (generated files land in
+ *   ~/nan-mcp-output/ by default).
+ * - Version pinning follows the upstream server's own supply-chain guidance:
+ *   NAN_MEDIA_MCP_VERSION (default "1.0.7"), or pass a custom command with
+ *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.0.7").
+ */
+
+import { Type, type TSchema } from "@earendil-works/pi-ai";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { callStdioMcpTool } from "./stdio-client.ts";
+import { NAN_API_KEY_ENV, resolveNanApiKey, type NapiKeyContext } from "./nan-search.ts";
+
+export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
+export const NAN_MEDIA_MCP_VERSION_ENV = "NAN_MEDIA_MCP_VERSION";
+export const NAN_MEDIA_MCP_COMMAND_ENV = "NAN_MEDIA_MCP_COMMAND";
+export const NAN_MEDIA_MCP_TIMEOUT_ENV = "NAN_MEDIA_MCP_TIMEOUT_MS";
+export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.0.7";
+export const DEFAULT_MEDIA_MCP_TIMEOUT_MS = 120_000;
+
+/** Media tools bridged from the stdio MCP server (audio/image/transcription scope). */
+export const NAN_MEDIA_TOOLS = [
+	"nan_generate_image",
+	"nan_edit_image",
+	"nan_text_to_speech",
+	"nan_list_voices",
+	"nan_speech_to_text",
+] as const;
+
+/** Truthy env parse: 1/true/on (case-insensitive). */
+function envEnabled(name: string): boolean {
+	const value = process.env[name]?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "on";
+}
+
+/** Whether the optional nan-mcp-server bridge is enabled (NAN_MEDIA_MCP=1). */
+export function mediaMcpEnabled(): boolean {
+	return envEnabled(NAN_MEDIA_MCP_ENV);
+}
+
+/** Default spawn: `npx -y nan-mcp-server@<pinned version>` (npx caches after first use). */
+export function mediaMcpCommand(version = process.env[NAN_MEDIA_MCP_VERSION_ENV] || DEFAULT_NAN_MEDIA_MCP_VERSION): string[] {
+	const custom = process.env[NAN_MEDIA_MCP_COMMAND_ENV]?.trim();
+	if (custom) return custom.split(/\s+/);
+	return ["npx", "-y", `nan-mcp-server@${version}`];
+}
+
+function mediaMcpTimeoutMs(): number {
+	const parsed = Number.parseInt(process.env[NAN_MEDIA_MCP_TIMEOUT_ENV] ?? "", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MEDIA_MCP_TIMEOUT_MS;
+}
+
+interface MediaToolSpec<TParams extends TSchema = TSchema> {
+	name: (typeof NAN_MEDIA_TOOLS)[number];
+	mcpTool: string;
+	label: string;
+	description: string;
+	promptSnippet: string;
+	parameters: TParams;
+}
+
+const sizeProperty = () =>
+	Type.Optional(
+		Type.String({
+			description: 'Image size "WxH" divisible by 16, e.g. 1024x1024, 1536x1024, 1024x1536. Default 1024x1024',
+		}),
+	);
+
+function defineMediaTool<TParams extends TSchema>(spec: MediaToolSpec<TParams>): ToolDefinition<TParams> {
+	return {
+		name: spec.name,
+		label: spec.label,
+		description: spec.description,
+		promptSnippet: spec.promptSnippet,
+		parameters: spec.parameters,
+		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+			const apiKey = await resolveNanApiKey(ctx as unknown as NapiKeyContext);
+			if (!apiKey) {
+				throw new Error(`${NAN_API_KEY_ENV} is not set. Export it or run /login nan to use NaN media tools.`);
+			}
+			const result = await callStdioMcpTool(spec.mcpTool, params as Record<string, unknown>, {
+				command: mediaMcpCommand(),
+				env: { [NAN_API_KEY_ENV]: apiKey },
+				timeoutMs: mediaMcpTimeoutMs(),
+				...(signal ? { signal } : {}),
+			});
+			if (!result.ok) {
+				throw new Error(
+					`${result.error ?? "nan-mcp-server call failed"}${result.stderrTail ? ` (server stderr: ${result.stderrTail})` : ""}`,
+				);
+			}
+			return { content: [{ type: "text", text: result.text }], details: undefined } as const;
+		},
+	};
+}
+
+/**
+ * Build the media tool set. Registered only when NAN_MEDIA_MCP=1 and the
+ * runtime supports registerTool; execution spawns the MCP server per call.
+ * Schemas mirror nan-mcp-server's zod input schemas (v1.0.7).
+ */
+export function createNanMediaTools(): ToolDefinition[] {
+	return [
+		defineMediaTool({
+			name: "nan_generate_image",
+			mcpTool: "generate_image",
+			label: "NaN Generate Image",
+			description:
+				"Generate an image with flux-2-klein (NaN API). Returns the saved image file path (under ~/nan-mcp-output/ by default) and its URL.",
+			promptSnippet: "nan_generate_image(prompt, size?, n?, seed?, guidance?, outputName?): generate an image via NaN (flux-2-klein)",
+			parameters: Type.Object({
+				prompt: Type.String({ description: "Textual description of the image to generate" }),
+				size: sizeProperty(),
+				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),
+				seed: Type.Optional(Type.Number({ description: "Base seed for reproducibility" })),
+				guidance: Type.Optional(Type.Number({ description: "FLUX guidance scale" })),
+				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file(s)" })),
+			}),
+		}),
+		defineMediaTool({
+			name: "nan_edit_image",
+			mcpTool: "edit_image",
+			label: "NaN Edit Image",
+			description:
+				"Edit an image with flux-2-klein image-to-image (NaN API). Takes reference image files and applies a transformation. Returns the saved output image path.",
+			promptSnippet: "nan_edit_image(prompt, images, size?, n?, seed?, guidance?, outputName?): edit images via NaN (flux-2-klein)",
+			parameters: Type.Object({
+				prompt: Type.String({ description: "Description of the edit or transformation to apply" }),
+				images: Type.Array(Type.String(), {
+					description: "Absolute paths to reference image files (PNG, JPEG, WebP; up to 4, each < 25MB)",
+				}),
+				size: sizeProperty(),
+				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),
+				seed: Type.Optional(Type.Number({ description: "Base seed for reproducibility" })),
+				guidance: Type.Optional(Type.Number({ description: "FLUX guidance scale" })),
+				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file(s)" })),
+			}),
+		}),
+		defineMediaTool({
+			name: "nan_text_to_speech",
+			mcpTool: "text_to_speech",
+			label: "NaN Text To Speech",
+			description:
+				"Synthesize audio from text with kokoro (NaN API TTS). Returns the saved audio file path. Use nan_list_voices to see all available voices per language.",
+			promptSnippet: "nan_text_to_speech(text, voice?, format?, speed?, outputName?): synthesize speech via NaN (kokoro)",
+			parameters: Type.Object({
+				text: Type.String({ description: "Text to synthesize" }),
+				voice: Type.Optional(
+					Type.String({
+						description:
+							'Voice to use, e.g. "af_heart" (American English female), "ef_dora" (Spanish female), "em_alex" (Spanish male). Use nan_list_voices for the full catalog',
+					}),
+				),
+				format: Type.Optional(
+					Type.Unsafe<"mp3" | "wav" | "flac" | "aac" | "pcm" | "opus">({
+						type: "string",
+						enum: ["mp3", "wav", "flac", "aac", "pcm", "opus"],
+						description: "Audio format. Default mp3",
+					}),
+				),
+				speed: Type.Optional(Type.Number({ description: "Speech speed. Default 1.0" })),
+				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file" })),
+			}),
+		}),
+		defineMediaTool({
+			name: "nan_list_voices",
+			mcpTool: "list_voices",
+			label: "NaN List Voices",
+			description: "List all available kokoro TTS voices grouped by language.",
+			promptSnippet: "nan_list_voices(): list available kokoro TTS voices",
+			parameters: Type.Object({}),
+		}),
+		defineMediaTool({
+			name: "nan_speech_to_text",
+			mcpTool: "speech_to_text",
+			label: "NaN Speech To Text",
+			description: "Transcribe an audio file with whisper (NaN API STT). Returns the transcript.",
+			promptSnippet: "nan_speech_to_text(file, language?, verbose?): transcribe an audio file via NaN (whisper)",
+			parameters: Type.Object({
+				file: Type.String({ description: "Absolute path to the audio file to transcribe" }),
+				language: Type.Optional(
+					Type.String({ description: 'ISO-639-1 language code, e.g. "es", "en". Auto-detected if omitted' }),
+				),
+				verbose: Type.Optional(Type.Boolean({ description: "Return verbose JSON with segments instead of plain text" })),
+			}),
+		}),
+	];
+}