@vertana/facade 0.1.0-dev.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,157 @@
+const require_result = require('./result.cjs');
+let _logtape_logtape = require("@logtape/logtape");
+let _vertana_core = require("@vertana/core");
+
+//#region src/index.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"vertana",
+	"facade",
+	"translate"
+]);
+/**
+* Translates the given text to the specified target language using the provided
+* language model(s).
+*
+* @param model The language model or models to use for translation.
+*              If multiple models are provided, they will be used for
+*              best-of-N selection.
+* @param targetLanguage The target language for the translation.  This can be
+*                       specified as an `Intl.Locale` object or a BCP 47
+*                       language tag string.
+* @param text The text to be translated.
+* @param options Optional settings for the translation process.
+* @returns A promise that resolves to the translation result.
+* @throws {Error} If the translation stream ends without a completion event.
+*/
+async function translate(model, targetLanguage, text, options) {
+	const startTime = performance.now();
+	logger.info("Starting translation...", {
+		targetLanguage: targetLanguage.toString(),
+		textLength: text.length
+	});
+	const models = Array.isArray(model) ? model : [model];
+	const primaryModel = models[0];
+	const bestOfNOptions = models.length > 1 && options?.bestOfN != null && options.bestOfN !== false ? options.bestOfN === true ? {} : options.bestOfN : null;
+	const dynamicGlossaryOptions = options?.dynamicGlossary != null && options.dynamicGlossary !== false ? options.dynamicGlossary === true ? {} : options.dynamicGlossary : null;
+	let gatheredContext = "";
+	if (options?.contextSources != null && options.contextSources.length > 0) {
+		options?.onProgress?.({
+			stage: "gatheringContext",
+			progress: 0
+		});
+		gatheredContext = (0, _vertana_core.combineContextResults)(await (0, _vertana_core.gatherRequiredContext)(options.contextSources, options?.signal));
+		options?.onProgress?.({
+			stage: "gatheringContext",
+			progress: 1
+		});
+		logger.debug("Context gathering completed.", { contextLength: gatheredContext.length });
+	}
+	const combinedContext = [options?.context, gatheredContext].filter((c) => c != null && c.trim().length > 0).join("\n\n");
+	const chunkingEnabled = options?.chunker !== null;
+	if (chunkingEnabled) options?.onProgress?.({
+		stage: "chunking",
+		progress: 0
+	});
+	const maxTokens = options?.contextWindow?.type === "explicit" ? options.contextWindow.maxTokens : 4096;
+	const sourceChunks = await (0, _vertana_core.chunkText)(text, {
+		chunker: options?.chunker,
+		mediaType: options?.mediaType,
+		maxTokens,
+		signal: options?.signal
+	});
+	if (chunkingEnabled) {
+		options?.onProgress?.({
+			stage: "chunking",
+			progress: 1
+		});
+		logger.debug("Chunking completed.", { chunkCount: sourceChunks.length });
+	}
+	const passiveSources = (options?.contextSources ?? []).filter((s) => s.mode === "passive");
+	let tools;
+	if (passiveSources.length > 0) {
+		options?.onProgress?.({
+			stage: "prompting",
+			progress: 0
+		});
+		tools = await (0, _vertana_core.createToolSet)(passiveSources, options?.signal);
+		options?.onProgress?.({
+			stage: "prompting",
+			progress: 1
+		});
+	}
+	const initialGlossary = options?.glossary ?? [];
+	const totalChunks = sourceChunks.length;
+	const modelsToUse = bestOfNOptions != null ? models : [primaryModel];
+	options?.onProgress?.({
+		stage: "translating",
+		progress: 0,
+		chunkIndex: 0,
+		totalChunks
+	});
+	const refinementOptions = options?.refinement != null && options.refinement !== false ? options.refinement === true ? {} : options.refinement : null;
+	let state = (0, _vertana_core.createInitialAccumulatorState)();
+	for await (const event of (0, _vertana_core.translateChunks)(sourceChunks, {
+		targetLanguage,
+		sourceLanguage: options?.sourceLanguage,
+		title: options?.title,
+		tone: options?.tone,
+		domain: options?.domain,
+		mediaType: options?.mediaType,
+		context: combinedContext || void 0,
+		glossary: initialGlossary,
+		models: modelsToUse,
+		evaluatorModel: bestOfNOptions?.evaluatorModel,
+		dynamicGlossary: dynamicGlossaryOptions,
+		refinement: refinementOptions,
+		tools,
+		signal: options?.signal
+	})) {
+		state = (0, _vertana_core.accumulateEvent)(state, event);
+		if (event.type === "chunk") {
+			options?.onProgress?.({
+				stage: "translating",
+				progress: (event.index + 1) / totalChunks,
+				chunkIndex: event.index,
+				totalChunks
+			});
+			if (event.selectedModel != null) options?.onProgress?.({
+				stage: "selecting",
+				progress: 1,
+				totalCandidates: modelsToUse.length
+			});
+			if (event.index === totalChunks - 1 && refinementOptions != null) options?.onProgress?.({
+				stage: "refining",
+				progress: 0,
+				maxIterations: refinementOptions.maxIterations ?? 3,
+				totalChunks
+			});
+		}
+	}
+	if (state.complete?.refinementIterations != null) options?.onProgress?.({
+		stage: "refining",
+		progress: 1,
+		iteration: state.complete.refinementIterations,
+		maxIterations: refinementOptions?.maxIterations ?? 3,
+		totalChunks
+	});
+	const result = require_result.buildTranslation(state, {
+		startTime,
+		extractTitle: options?.title != null
+	});
+	logger.info("Translation completed.", {
+		processingTimeMs: result.processingTime,
+		tokensUsed: result.tokenUsed,
+		qualityScore: result.qualityScore,
+		chunkCount: state.complete?.translations.length ?? 0
+	});
+	return result;
+}
+
+//#endregion
+Object.defineProperty(exports, 'extractTerms', {
+  enumerable: true,
+  get: function () {
+    return _vertana_core.extractTerms;
+  }
+});
+exports.translate = translate;

package/dist/index.d.cts

@@ -0,0 +1,24 @@
+import { BestOfNOptions, ChunkingProgress, DynamicGlossaryOptions, GatheringContextProgress, MediaType, PromptingProgress, RefinementOptions, RefiningProgress, SelectingProgress, TranslateOptions, TranslatingProgress, Translation, TranslationProgress, TranslationTone } from "./types.cjs";
+import { LanguageModel } from "ai";
+import { extractTerms } from "@vertana/core";
+
+//#region src/index.d.ts
+
+/**
+ * Translates the given text to the specified target language using the provided
+ * language model(s).
+ *
+ * @param model The language model or models to use for translation.
+ *              If multiple models are provided, they will be used for
+ *              best-of-N selection.
+ * @param targetLanguage The target language for the translation.  This can be
+ *                       specified as an `Intl.Locale` object or a BCP 47
+ *                       language tag string.
+ * @param text The text to be translated.
+ * @param options Optional settings for the translation process.
+ * @returns A promise that resolves to the translation result.
+ * @throws {Error} If the translation stream ends without a completion event.
+ */
+declare function translate(model: LanguageModel | readonly LanguageModel[], targetLanguage: Intl.Locale | string, text: string, options?: TranslateOptions): Promise<Translation>;
+//#endregion
+export { type BestOfNOptions, type ChunkingProgress, type DynamicGlossaryOptions, type GatheringContextProgress, type MediaType, type PromptingProgress, type RefinementOptions, type RefiningProgress, type SelectingProgress, type TranslateOptions, type TranslatingProgress, type Translation, type TranslationProgress, type TranslationTone, extractTerms, translate };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { BestOfNOptions, ChunkingProgress, DynamicGlossaryOptions, GatheringContextProgress, MediaType, PromptingProgress, RefinementOptions, RefiningProgress, SelectingProgress, TranslateOptions, TranslatingProgress, Translation, TranslationProgress, TranslationTone } from "./types.js";
+import { extractTerms } from "@vertana/core";
+import { LanguageModel } from "ai";
+
+//#region src/index.d.ts
+
+/**
+ * Translates the given text to the specified target language using the provided
+ * language model(s).
+ *
+ * @param model The language model or models to use for translation.
+ *              If multiple models are provided, they will be used for
+ *              best-of-N selection.
+ * @param targetLanguage The target language for the translation.  This can be
+ *                       specified as an `Intl.Locale` object or a BCP 47
+ *                       language tag string.
+ * @param text The text to be translated.
+ * @param options Optional settings for the translation process.
+ * @returns A promise that resolves to the translation result.
+ * @throws {Error} If the translation stream ends without a completion event.
+ */
+declare function translate(model: LanguageModel | readonly LanguageModel[], targetLanguage: Intl.Locale | string, text: string, options?: TranslateOptions): Promise<Translation>;
+//#endregion
+export { type BestOfNOptions, type ChunkingProgress, type DynamicGlossaryOptions, type GatheringContextProgress, type MediaType, type PromptingProgress, type RefinementOptions, type RefiningProgress, type SelectingProgress, type TranslateOptions, type TranslatingProgress, type Translation, type TranslationProgress, type TranslationTone, extractTerms, translate };

package/dist/index.js

@@ -0,0 +1,151 @@
+import { buildTranslation } from "./result.js";
+import { getLogger } from "@logtape/logtape";
+import { accumulateEvent, chunkText, combineContextResults, createInitialAccumulatorState, createToolSet, extractTerms, gatherRequiredContext, translateChunks } from "@vertana/core";
+
+//#region src/index.ts
+const logger = getLogger([
+	"vertana",
+	"facade",
+	"translate"
+]);
+/**
+* Translates the given text to the specified target language using the provided
+* language model(s).
+*
+* @param model The language model or models to use for translation.
+*              If multiple models are provided, they will be used for
+*              best-of-N selection.
+* @param targetLanguage The target language for the translation.  This can be
+*                       specified as an `Intl.Locale` object or a BCP 47
+*                       language tag string.
+* @param text The text to be translated.
+* @param options Optional settings for the translation process.
+* @returns A promise that resolves to the translation result.
+* @throws {Error} If the translation stream ends without a completion event.
+*/
+async function translate(model, targetLanguage, text, options) {
+	const startTime = performance.now();
+	logger.info("Starting translation...", {
+		targetLanguage: targetLanguage.toString(),
+		textLength: text.length
+	});
+	const models = Array.isArray(model) ? model : [model];
+	const primaryModel = models[0];
+	const bestOfNOptions = models.length > 1 && options?.bestOfN != null && options.bestOfN !== false ? options.bestOfN === true ? {} : options.bestOfN : null;
+	const dynamicGlossaryOptions = options?.dynamicGlossary != null && options.dynamicGlossary !== false ? options.dynamicGlossary === true ? {} : options.dynamicGlossary : null;
+	let gatheredContext = "";
+	if (options?.contextSources != null && options.contextSources.length > 0) {
+		options?.onProgress?.({
+			stage: "gatheringContext",
+			progress: 0
+		});
+		gatheredContext = combineContextResults(await gatherRequiredContext(options.contextSources, options?.signal));
+		options?.onProgress?.({
+			stage: "gatheringContext",
+			progress: 1
+		});
+		logger.debug("Context gathering completed.", { contextLength: gatheredContext.length });
+	}
+	const combinedContext = [options?.context, gatheredContext].filter((c) => c != null && c.trim().length > 0).join("\n\n");
+	const chunkingEnabled = options?.chunker !== null;
+	if (chunkingEnabled) options?.onProgress?.({
+		stage: "chunking",
+		progress: 0
+	});
+	const maxTokens = options?.contextWindow?.type === "explicit" ? options.contextWindow.maxTokens : 4096;
+	const sourceChunks = await chunkText(text, {
+		chunker: options?.chunker,
+		mediaType: options?.mediaType,
+		maxTokens,
+		signal: options?.signal
+	});
+	if (chunkingEnabled) {
+		options?.onProgress?.({
+			stage: "chunking",
+			progress: 1
+		});
+		logger.debug("Chunking completed.", { chunkCount: sourceChunks.length });
+	}
+	const passiveSources = (options?.contextSources ?? []).filter((s) => s.mode === "passive");
+	let tools;
+	if (passiveSources.length > 0) {
+		options?.onProgress?.({
+			stage: "prompting",
+			progress: 0
+		});
+		tools = await createToolSet(passiveSources, options?.signal);
+		options?.onProgress?.({
+			stage: "prompting",
+			progress: 1
+		});
+	}
+	const initialGlossary = options?.glossary ?? [];
+	const totalChunks = sourceChunks.length;
+	const modelsToUse = bestOfNOptions != null ? models : [primaryModel];
+	options?.onProgress?.({
+		stage: "translating",
+		progress: 0,
+		chunkIndex: 0,
+		totalChunks
+	});
+	const refinementOptions = options?.refinement != null && options.refinement !== false ? options.refinement === true ? {} : options.refinement : null;
+	let state = createInitialAccumulatorState();
+	for await (const event of translateChunks(sourceChunks, {
+		targetLanguage,
+		sourceLanguage: options?.sourceLanguage,
+		title: options?.title,
+		tone: options?.tone,
+		domain: options?.domain,
+		mediaType: options?.mediaType,
+		context: combinedContext || void 0,
+		glossary: initialGlossary,
+		models: modelsToUse,
+		evaluatorModel: bestOfNOptions?.evaluatorModel,
+		dynamicGlossary: dynamicGlossaryOptions,
+		refinement: refinementOptions,
+		tools,
+		signal: options?.signal
+	})) {
+		state = accumulateEvent(state, event);
+		if (event.type === "chunk") {
+			options?.onProgress?.({
+				stage: "translating",
+				progress: (event.index + 1) / totalChunks,
+				chunkIndex: event.index,
+				totalChunks
+			});
+			if (event.selectedModel != null) options?.onProgress?.({
+				stage: "selecting",
+				progress: 1,
+				totalCandidates: modelsToUse.length
+			});
+			if (event.index === totalChunks - 1 && refinementOptions != null) options?.onProgress?.({
+				stage: "refining",
+				progress: 0,
+				maxIterations: refinementOptions.maxIterations ?? 3,
+				totalChunks
+			});
+		}
+	}
+	if (state.complete?.refinementIterations != null) options?.onProgress?.({
+		stage: "refining",
+		progress: 1,
+		iteration: state.complete.refinementIterations,
+		maxIterations: refinementOptions?.maxIterations ?? 3,
+		totalChunks
+	});
+	const result = buildTranslation(state, {
+		startTime,
+		extractTitle: options?.title != null
+	});
+	logger.info("Translation completed.", {
+		processingTimeMs: result.processingTime,
+		tokensUsed: result.tokenUsed,
+		qualityScore: result.qualityScore,
+		chunkCount: state.complete?.translations.length ?? 0
+	});
+	return result;
+}
+
+//#endregion
+export { extractTerms, translate };

package/dist/result.cjs

@@ -0,0 +1,32 @@
+let _vertana_core = require("@vertana/core");
+
+//#region src/result.ts
+/**
+* Builds the final translation result from accumulated stream state.
+*
+* @param state The accumulated state from processing the translation stream.
+* @param options Options for building the result.
+* @returns The translation result.
+* @throws {Error} If the translation stream did not complete.
+*/
+function buildTranslation(state, options) {
+	const { complete, totalQualityScore, qualityScoreCount, modelWinCounts } = state;
+	if (complete == null) throw new Error("Translation did not complete.");
+	const text = complete.translations.join("\n\n");
+	const processingTime = performance.now() - options.startTime;
+	const qualityScore = complete.qualityScore ?? (qualityScoreCount > 0 ? totalQualityScore / qualityScoreCount : void 0);
+	const selectedModel = (0, _vertana_core.maxByValue)(modelWinCounts);
+	return {
+		text,
+		title: options.extractTitle ? (0, _vertana_core.extractTitle)(text) : void 0,
+		tokenUsed: complete.totalTokensUsed,
+		processingTime,
+		qualityScore,
+		refinementIterations: complete.refinementIterations,
+		selectedModel,
+		accumulatedGlossary: complete.accumulatedGlossary.length > 0 ? complete.accumulatedGlossary : void 0
+	};
+}
+
+//#endregion
+exports.buildTranslation = buildTranslation;

package/dist/result.js

@@ -0,0 +1,32 @@
+import { extractTitle, maxByValue } from "@vertana/core";
+
+//#region src/result.ts
+/**
+* Builds the final translation result from accumulated stream state.
+*
+* @param state The accumulated state from processing the translation stream.
+* @param options Options for building the result.
+* @returns The translation result.
+* @throws {Error} If the translation stream did not complete.
+*/
+function buildTranslation(state, options) {
+	const { complete, totalQualityScore, qualityScoreCount, modelWinCounts } = state;
+	if (complete == null) throw new Error("Translation did not complete.");
+	const text = complete.translations.join("\n\n");
+	const processingTime = performance.now() - options.startTime;
+	const qualityScore = complete.qualityScore ?? (qualityScoreCount > 0 ? totalQualityScore / qualityScoreCount : void 0);
+	const selectedModel = maxByValue(modelWinCounts);
+	return {
+		text,
+		title: options.extractTitle ? extractTitle(text) : void 0,
+		tokenUsed: complete.totalTokensUsed,
+		processingTime,
+		qualityScore,
+		refinementIterations: complete.refinementIterations,
+		selectedModel,
+		accumulatedGlossary: complete.accumulatedGlossary.length > 0 ? complete.accumulatedGlossary : void 0
+	};
+}
+
+//#endregion
+export { buildTranslation };

package/dist/types.d.cts

@@ -0,0 +1,282 @@
+import { LanguageModel } from "ai";
+import { Chunker, ContextSource, ContextWindow, Glossary, MediaType, MediaType as MediaType$1, TranslationTone, TranslationTone as TranslationTone$1 } from "@vertana/core";
+
+//#region src/types.d.ts
+
+/**
+ * Base progress information shared by all stages.
+ */
+interface BaseProgress {
+  /**
+   * The progress percentage (0 to 1) of the current stage.
+   */
+  readonly progress: number;
+}
+/**
+ * Progress information for the chunking stage.
+ */
+interface ChunkingProgress extends BaseProgress {
+  readonly stage: "chunking";
+}
+/**
+ * Progress information for the prompting stage.
+ */
+interface PromptingProgress extends BaseProgress {
+  readonly stage: "prompting";
+}
+/**
+ * Progress information for the context gathering stage.
+ */
+interface GatheringContextProgress extends BaseProgress {
+  readonly stage: "gatheringContext";
+}
+/**
+ * Progress information for the translating stage.
+ */
+interface TranslatingProgress extends BaseProgress {
+  readonly stage: "translating";
+  /**
+   * When chunking is used, indicates the current chunk index (0-based).
+   */
+  readonly chunkIndex?: number;
+  /**
+   * When chunking is used, indicates total number of chunks.
+   */
+  readonly totalChunks?: number;
+}
+/**
+ * Progress information for the refining stage.
+ */
+interface RefiningProgress extends BaseProgress {
+  readonly stage: "refining";
+  /**
+   * The current refinement iteration (1-based).
+   */
+  readonly iteration?: number;
+  /**
+   * The maximum number of refinement iterations.
+   */
+  readonly maxIterations?: number;
+  /**
+   * When refining chunks, indicates the current chunk index (0-based).
+   */
+  readonly chunkIndex?: number;
+  /**
+   * When refining chunks, indicates total number of chunks.
+   */
+  readonly totalChunks?: number;
+}
+/**
+ * Progress information for the best-of-N selection stage.
+ */
+interface SelectingProgress extends BaseProgress {
+  readonly stage: "selecting";
+  /**
+   * The current candidate being evaluated (0-based).
+   */
+  readonly candidateIndex?: number;
+  /**
+   * The total number of candidates.
+   */
+  readonly totalCandidates?: number;
+}
+/**
+ * Progress information for the translation process.
+ */
+type TranslationProgress = ChunkingProgress | PromptingProgress | GatheringContextProgress | TranslatingProgress | RefiningProgress | SelectingProgress;
+/**
+ * The result of a translation operation.
+ */
+interface Translation {
+  /**
+   * The translated text.
+   */
+  readonly text: string;
+  /**
+   * An optional title for the translated text, if provided.
+   */
+  readonly title?: string;
+  /**
+   * The total number of tokens used during the translation process.
+   */
+  readonly tokenUsed: number;
+  /**
+   * The time taken to process the translation, in milliseconds.
+   */
+  readonly processingTime: number;
+  /**
+   * The final quality score after refinement (0-1).
+   * Only present when refinement is enabled.
+   */
+  readonly qualityScore?: number;
+  /**
+   * The number of refinement iterations performed.
+   * Only present when refinement is enabled.
+   */
+  readonly refinementIterations?: number;
+  /**
+   * The model that produced the best translation.
+   * Only present when best-of-N selection is used with multiple models.
+   */
+  readonly selectedModel?: LanguageModel;
+  /**
+   * The accumulated glossary from dynamic term extraction.
+   * Only present when dynamic glossary is enabled.
+   */
+  readonly accumulatedGlossary?: Glossary;
+}
+/**
+ * Options for iterative translation refinement.
+ */
+interface RefinementOptions {
+  /**
+   * Maximum number of refinement iterations.
+   *
+   * @default `3`
+   */
+  readonly maxIterations?: number;
+  /**
+   * Quality threshold (0-1).  If the evaluation score exceeds this threshold,
+   * refinement stops early.
+   *
+   * @default `0.9`
+   */
+  readonly qualityThreshold?: number;
+}
+/**
+ * Options for best-of-N selection when multiple models are provided.
+ */
+interface BestOfNOptions {
+  /**
+   * The model to use for evaluating and selecting the best translation.
+   * If not specified, the first model in the array is used.
+   */
+  readonly evaluatorModel?: LanguageModel;
+}
+/**
+ * Options for dynamic glossary accumulation during translation.
+ */
+interface DynamicGlossaryOptions {
+  /**
+   * Maximum number of terms to extract from each chunk.
+   *
+   * @default `10`
+   */
+  readonly maxTermsPerChunk?: number;
+  /**
+   * The model to use for extracting terms.
+   * If not specified, the primary translation model is used.
+   */
+  readonly extractorModel?: LanguageModel;
+}
+/**
+ * Options for the translate function.
+ */
+interface TranslateOptions {
+  /**
+   * The source language of the input text.  If not provided, the language will
+   * be auto-detected.
+   *
+   * If a string is provided, it should be a valid BCP 47 language tag.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * An optional title for the input text.  It's also translated if provided.
+   */
+  readonly title?: string;
+  /**
+   * Additional context or background information about the input text.  This
+   * can help improve translation accuracy.
+   */
+  readonly context?: string;
+  /**
+   * The desired tone for the translated text.  This helps tailor the style
+   * and formality of the output.
+   */
+  readonly tone?: TranslationTone;
+  /**
+   * The domain or context of the input text, e.g., `"medical"`, `"legal"`,
+   * `"technical"`, etc.  This helps the model produce more accurate
+   * translations by tailoring the output to the specific field.
+   */
+  readonly domain?: string;
+  /**
+   * The media type of the input text.  This hints at the formatting and
+   * structure of the content so that the model can maintain it in
+   * the translation.
+   *
+   * @default `"text/plain"`
+   */
+  readonly mediaType?: MediaType;
+  /**
+   * An optional callback function that is invoked to report progress
+   * during the translation process.
+   *
+   * @param progress The current progress information.
+   */
+  readonly onProgress?: (progress: TranslationProgress) => void;
+  /**
+   * An optional `AbortSignal` to cancel the translation request.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Context sources to gather additional information for translation.
+   * These can be either required (always invoked) or passive (invoked by
+   * the LLM agent on demand).
+   */
+  readonly contextSources?: readonly ContextSource[];
+  /**
+   * A glossary of terms for consistent translation.  Terms in the glossary
+   * will be translated consistently throughout the document.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * Context window management strategy.  This controls how the translation
+   * handles long documents that may exceed the model's context window.
+   *
+   * @default `{ type: "explicit", maxTokens: 8192 }`
+   */
+  readonly contextWindow?: ContextWindow;
+  /**
+   * Refinement settings for iterative translation improvement.  When enabled,
+   * the translation will be evaluated and refined until the quality threshold
+   * is met or the maximum number of iterations is reached.
+   *
+   * - `true`: Enable refinement with default settings.
+   * - `RefinementOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled.
+   */
+  readonly refinement?: boolean | RefinementOptions;
+  /**
+   * A custom chunker function for splitting long texts.  If not provided,
+   * a default chunker is selected based on `mediaType`:
+   *
+   * - `"text/markdown"`: Markdown-aware chunker
+   * - `"text/plain"` or `"text/html"`: Paragraph-based chunker
+   *
+   * Set to `null` to disable chunking entirely.
+   */
+  readonly chunker?: Chunker | null;
+  /**
+   * Best-of-N selection settings.  When multiple models are provided and this
+   * is enabled, each model generates a translation and the best one is selected
+   * based on evaluation scores.
+   *
+   * - `true`: Enable best-of-N selection with default settings.
+   * - `BestOfNOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled (only first model is used).
+   */
+  readonly bestOfN?: boolean | BestOfNOptions;
+  /**
+   * Dynamic glossary accumulation settings.  When enabled, key terminology
+   * pairs are extracted from each translated chunk and accumulated for use
+   * in subsequent chunks, improving terminology consistency.
+   *
+   * - `true`: Enable dynamic glossary with default settings.
+   * - `DynamicGlossaryOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled.
+   */
+  readonly dynamicGlossary?: boolean | DynamicGlossaryOptions;
+}
+//#endregion
+export { BestOfNOptions, ChunkingProgress, DynamicGlossaryOptions, GatheringContextProgress, type MediaType$1 as MediaType, PromptingProgress, RefinementOptions, RefiningProgress, SelectingProgress, TranslateOptions, TranslatingProgress, Translation, TranslationProgress, type TranslationTone$1 as TranslationTone };

package/dist/types.d.ts

@@ -0,0 +1,282 @@
+import { Chunker, ContextSource, ContextWindow, Glossary, MediaType, MediaType as MediaType$1, TranslationTone, TranslationTone as TranslationTone$1 } from "@vertana/core";
+import { LanguageModel } from "ai";
+
+//#region src/types.d.ts
+
+/**
+ * Base progress information shared by all stages.
+ */
+interface BaseProgress {
+  /**
+   * The progress percentage (0 to 1) of the current stage.
+   */
+  readonly progress: number;
+}
+/**
+ * Progress information for the chunking stage.
+ */
+interface ChunkingProgress extends BaseProgress {
+  readonly stage: "chunking";
+}
+/**
+ * Progress information for the prompting stage.
+ */
+interface PromptingProgress extends BaseProgress {
+  readonly stage: "prompting";
+}
+/**
+ * Progress information for the context gathering stage.
+ */
+interface GatheringContextProgress extends BaseProgress {
+  readonly stage: "gatheringContext";
+}
+/**
+ * Progress information for the translating stage.
+ */
+interface TranslatingProgress extends BaseProgress {
+  readonly stage: "translating";
+  /**
+   * When chunking is used, indicates the current chunk index (0-based).
+   */
+  readonly chunkIndex?: number;
+  /**
+   * When chunking is used, indicates total number of chunks.
+   */
+  readonly totalChunks?: number;
+}
+/**
+ * Progress information for the refining stage.
+ */
+interface RefiningProgress extends BaseProgress {
+  readonly stage: "refining";
+  /**
+   * The current refinement iteration (1-based).
+   */
+  readonly iteration?: number;
+  /**
+   * The maximum number of refinement iterations.
+   */
+  readonly maxIterations?: number;
+  /**
+   * When refining chunks, indicates the current chunk index (0-based).
+   */
+  readonly chunkIndex?: number;
+  /**
+   * When refining chunks, indicates total number of chunks.
+   */
+  readonly totalChunks?: number;
+}
+/**
+ * Progress information for the best-of-N selection stage.
+ */
+interface SelectingProgress extends BaseProgress {
+  readonly stage: "selecting";
+  /**
+   * The current candidate being evaluated (0-based).
+   */
+  readonly candidateIndex?: number;
+  /**
+   * The total number of candidates.
+   */
+  readonly totalCandidates?: number;
+}
+/**
+ * Progress information for the translation process.
+ */
+type TranslationProgress = ChunkingProgress | PromptingProgress | GatheringContextProgress | TranslatingProgress | RefiningProgress | SelectingProgress;
+/**
+ * The result of a translation operation.
+ */
+interface Translation {
+  /**
+   * The translated text.
+   */
+  readonly text: string;
+  /**
+   * An optional title for the translated text, if provided.
+   */
+  readonly title?: string;
+  /**
+   * The total number of tokens used during the translation process.
+   */
+  readonly tokenUsed: number;
+  /**
+   * The time taken to process the translation, in milliseconds.
+   */
+  readonly processingTime: number;
+  /**
+   * The final quality score after refinement (0-1).
+   * Only present when refinement is enabled.
+   */
+  readonly qualityScore?: number;
+  /**
+   * The number of refinement iterations performed.
+   * Only present when refinement is enabled.
+   */
+  readonly refinementIterations?: number;
+  /**
+   * The model that produced the best translation.
+   * Only present when best-of-N selection is used with multiple models.
+   */
+  readonly selectedModel?: LanguageModel;
+  /**
+   * The accumulated glossary from dynamic term extraction.
+   * Only present when dynamic glossary is enabled.
+   */
+  readonly accumulatedGlossary?: Glossary;
+}
+/**
+ * Options for iterative translation refinement.
+ */
+interface RefinementOptions {
+  /**
+   * Maximum number of refinement iterations.
+   *
+   * @default `3`
+   */
+  readonly maxIterations?: number;
+  /**
+   * Quality threshold (0-1).  If the evaluation score exceeds this threshold,
+   * refinement stops early.
+   *
+   * @default `0.9`
+   */
+  readonly qualityThreshold?: number;
+}
+/**
+ * Options for best-of-N selection when multiple models are provided.
+ */
+interface BestOfNOptions {
+  /**
+   * The model to use for evaluating and selecting the best translation.
+   * If not specified, the first model in the array is used.
+   */
+  readonly evaluatorModel?: LanguageModel;
+}
+/**
+ * Options for dynamic glossary accumulation during translation.
+ */
+interface DynamicGlossaryOptions {
+  /**
+   * Maximum number of terms to extract from each chunk.
+   *
+   * @default `10`
+   */
+  readonly maxTermsPerChunk?: number;
+  /**
+   * The model to use for extracting terms.
+   * If not specified, the primary translation model is used.
+   */
+  readonly extractorModel?: LanguageModel;
+}
+/**
+ * Options for the translate function.
+ */
+interface TranslateOptions {
+  /**
+   * The source language of the input text.  If not provided, the language will
+   * be auto-detected.
+   *
+   * If a string is provided, it should be a valid BCP 47 language tag.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * An optional title for the input text.  It's also translated if provided.
+   */
+  readonly title?: string;
+  /**
+   * Additional context or background information about the input text.  This
+   * can help improve translation accuracy.
+   */
+  readonly context?: string;
+  /**
+   * The desired tone for the translated text.  This helps tailor the style
+   * and formality of the output.
+   */
+  readonly tone?: TranslationTone;
+  /**
+   * The domain or context of the input text, e.g., `"medical"`, `"legal"`,
+   * `"technical"`, etc.  This helps the model produce more accurate
+   * translations by tailoring the output to the specific field.
+   */
+  readonly domain?: string;
+  /**
+   * The media type of the input text.  This hints at the formatting and
+   * structure of the content so that the model can maintain it in
+   * the translation.
+   *
+   * @default `"text/plain"`
+   */
+  readonly mediaType?: MediaType;
+  /**
+   * An optional callback function that is invoked to report progress
+   * during the translation process.
+   *
+   * @param progress The current progress information.
+   */
+  readonly onProgress?: (progress: TranslationProgress) => void;
+  /**
+   * An optional `AbortSignal` to cancel the translation request.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Context sources to gather additional information for translation.
+   * These can be either required (always invoked) or passive (invoked by
+   * the LLM agent on demand).
+   */
+  readonly contextSources?: readonly ContextSource[];
+  /**
+   * A glossary of terms for consistent translation.  Terms in the glossary
+   * will be translated consistently throughout the document.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * Context window management strategy.  This controls how the translation
+   * handles long documents that may exceed the model's context window.
+   *
+   * @default `{ type: "explicit", maxTokens: 8192 }`
+   */
+  readonly contextWindow?: ContextWindow;
+  /**
+   * Refinement settings for iterative translation improvement.  When enabled,
+   * the translation will be evaluated and refined until the quality threshold
+   * is met or the maximum number of iterations is reached.
+   *
+   * - `true`: Enable refinement with default settings.
+   * - `RefinementOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled.
+   */
+  readonly refinement?: boolean | RefinementOptions;
+  /**
+   * A custom chunker function for splitting long texts.  If not provided,
+   * a default chunker is selected based on `mediaType`:
+   *
+   * - `"text/markdown"`: Markdown-aware chunker
+   * - `"text/plain"` or `"text/html"`: Paragraph-based chunker
+   *
+   * Set to `null` to disable chunking entirely.
+   */
+  readonly chunker?: Chunker | null;
+  /**
+   * Best-of-N selection settings.  When multiple models are provided and this
+   * is enabled, each model generates a translation and the best one is selected
+   * based on evaluation scores.
+   *
+   * - `true`: Enable best-of-N selection with default settings.
+   * - `BestOfNOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled (only first model is used).
+   */
+  readonly bestOfN?: boolean | BestOfNOptions;
+  /**
+   * Dynamic glossary accumulation settings.  When enabled, key terminology
+   * pairs are extracted from each translated chunk and accumulated for use
+   * in subsequent chunks, improving terminology consistency.
+   *
+   * - `true`: Enable dynamic glossary with default settings.
+   * - `DynamicGlossaryOptions`: Enable with custom settings.
+   * - `undefined` or `false`: Disabled.
+   */
+  readonly dynamicGlossary?: boolean | DynamicGlossaryOptions;
+}
+//#endregion
+export { BestOfNOptions, ChunkingProgress, DynamicGlossaryOptions, GatheringContextProgress, type MediaType$1 as MediaType, PromptingProgress, RefinementOptions, RefiningProgress, SelectingProgress, TranslateOptions, TranslatingProgress, Translation, TranslationProgress, type TranslationTone$1 as TranslationTone };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@vertana/facade",
+  "version": "0.1.0-dev.1",
+  "description": "An LLM-powered natural language translation facade library",
+  "keywords": [
+    "LLM",
+    "translation",
+    "natural language processing",
+    "NLP",
+    "language model"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://vertana.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/vertana.git",
+    "directory": "packages/facade"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/vertana/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "require": "./dist/index.d.cts",
+        "import": "./dist/index.d.ts"
+      },
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@logtape/logtape": "^1.3.5",
+    "@vertana/core": ""
+  },
+  "peerDependencies": {
+    "ai": "6.0.3"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "3.0.1",
+    "@ai-sdk/google": "3.0.1",
+    "@ai-sdk/openai": "3.0.1",
+    "@types/node": "^20.19.9",
+    "@valibot/to-json-schema": "^1.5.0",
+    "ai": "6.0.3",
+    "tsdown": "^0.18.3",
+    "typescript": "^5.9.3",
+    "valibot": "1.2.0",
+    "zod": "4.2.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test --test-concurrency=4",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test --allow-env --allow-net",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}