@vertana/core 0.1.0-dev.1

package/dist/prompt.d.ts

@@ -0,0 +1,74 @@
+import { Glossary } from "./glossary.js";
+
+//#region src/prompt.d.ts
+
+/**
+ * The media type of the input text.
+ *
+ * - `"text/plain"`: Plain text
+ * - `"text/html"`: HTML content
+ * - `"text/markdown"`: Markdown content
+ */
+type MediaType = "text/plain" | "text/html" | "text/markdown";
+/**
+ * The desired tone for the translated text.
+ */
+type TranslationTone = "formal" | "informal" | "technical" | "casual" | "professional" | "literary" | "journalistic";
+/**
+ * Gets the English display name for a language.
+ *
+ * @param language The language as an `Intl.Locale` or BCP 47 tag.
+ * @returns The English display name for the language.
+ */
+declare function getLanguageName(language: Intl.Locale | string): string;
+/**
+ * Options for building the system prompt.
+ */
+interface SystemPromptOptions {
+  readonly sourceLanguage?: Intl.Locale | string;
+  readonly tone?: TranslationTone;
+  readonly domain?: string;
+  readonly mediaType?: MediaType;
+  readonly context?: string;
+  readonly glossary?: Glossary;
+}
+/**
+ * Builds the system prompt for the translation.
+ *
+ * @param targetLanguage The target language for translation.
+ * @param options Additional options for the prompt.
+ * @returns The system prompt string.
+ */
+declare function buildSystemPrompt(targetLanguage: Intl.Locale | string, options?: SystemPromptOptions): string;
+/**
+ * Represents a previously translated chunk for context.
+ */
+interface TranslatedChunk {
+  readonly source: string;
+  readonly translation: string;
+}
+/**
+ * Builds the user prompt for the translation.
+ *
+ * @param text The text to translate.
+ * @param title An optional title to include.
+ * @returns The user prompt string.
+ */
+declare function buildUserPrompt(text: string, title?: string): string;
+/**
+ * Builds the user prompt with previous chunk context.
+ *
+ * @param text The text to translate.
+ * @param previousChunks Previously translated chunks for context.
+ * @returns The user prompt string with context.
+ */
+declare function buildUserPromptWithContext(text: string, previousChunks: readonly TranslatedChunk[]): string;
+/**
+ * Extracts the translated title from the translated text.
+ *
+ * @param translatedText The translated text that may contain a title.
+ * @returns The extracted title, or undefined if not found.
+ */
+declare function extractTitle(translatedText: string): string | undefined;
+//#endregion
+export { MediaType, SystemPromptOptions, TranslatedChunk, TranslationTone, buildSystemPrompt, buildUserPrompt, buildUserPromptWithContext, extractTitle, getLanguageName };

package/dist/prompt.js

@@ -0,0 +1,86 @@
+//#region src/prompt.ts
+const languageNames = new Intl.DisplayNames(["en"], { type: "language" });
+/**
+* Gets the English display name for a language.
+*
+* @param language The language as an `Intl.Locale` or BCP 47 tag.
+* @returns The English display name for the language.
+*/
+function getLanguageName(language) {
+	const tag = typeof language === "string" ? language : language.toString();
+	return languageNames.of(tag) ?? tag;
+}
+/**
+* Builds the system prompt for the translation.
+*
+* @param targetLanguage The target language for translation.
+* @param options Additional options for the prompt.
+* @returns The system prompt string.
+*/
+function buildSystemPrompt(targetLanguage, options) {
+	const parts = [
+		"You are a professional translator.",
+		`Translate the given text into ${getLanguageName(targetLanguage)}.`,
+		"Preserve the original meaning, tone, and nuance as accurately as possible.",
+		"Output only the translated text without any explanations or notes."
+	];
+	if (options?.sourceLanguage != null) {
+		const sourceLangName = getLanguageName(options.sourceLanguage);
+		parts.push(`The source language is ${sourceLangName}.`);
+	}
+	if (options?.tone != null) parts.push(`Use a ${options.tone} tone in the translation.`);
+	if (options?.domain != null) parts.push(`This text is from the ${options.domain} domain. Use appropriate terminology for this field.`);
+	if (options?.mediaType != null && options.mediaType !== "text/plain") {
+		const formatName = options.mediaType === "text/html" ? "HTML" : "Markdown";
+		parts.push(`The input is formatted as ${formatName}. Preserve the formatting structure in your translation.`);
+	}
+	if (options?.context != null) parts.push(`Additional context: ${options.context}`);
+	if (options?.glossary != null && options.glossary.length > 0) {
+		const glossaryLines = options.glossary.map((entry) => {
+			const contextNote = entry.context != null ? ` (${entry.context})` : "";
+			return `  - "${entry.original}" → "${entry.translated}"${contextNote}`;
+		});
+		parts.push("Use the following glossary for consistent terminology:\n" + glossaryLines.join("\n"));
+	}
+	return parts.join("\n\n");
+}
+/**
+* Builds the user prompt for the translation.
+*
+* @param text The text to translate.
+* @param title An optional title to include.
+* @returns The user prompt string.
+*/
+function buildUserPrompt(text, title) {
+	if (title != null) return `Title: ${title}\n\n${text}`;
+	return text;
+}
+/**
+* Builds the user prompt with previous chunk context.
+*
+* @param text The text to translate.
+* @param previousChunks Previously translated chunks for context.
+* @returns The user prompt string with context.
+*/
+function buildUserPromptWithContext(text, previousChunks) {
+	if (previousChunks.length === 0) return text;
+	return `The following sections have already been translated. Maintain consistency in terminology, style, and tone with the previous translations.
+
+${previousChunks.map((chunk, index) => {
+		return `[Previous section ${index + 1}]\nOriginal: ${chunk.source}\nTranslation: ${chunk.translation}`;
+	}).join("\n\n")}\n\n[Current section to translate]\n${text}`;
+}
+/**
+* Extracts the translated title from the translated text.
+*
+* @param translatedText The translated text that may contain a title.
+* @returns The extracted title, or undefined if not found.
+*/
+function extractTitle(translatedText) {
+	const match = translatedText.match(/^Title:\s*(.+?)(?:\n|$)/);
+	if (match != null) return match[1].trim();
+	return translatedText.split("\n")[0]?.trim() || void 0;
+}
+
+//#endregion
+export { buildSystemPrompt, buildUserPrompt, buildUserPromptWithContext, extractTitle, getLanguageName };

package/dist/refine.cjs

@@ -0,0 +1,243 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_evaluation = require('./evaluation.cjs');
+let _logtape_logtape = require("@logtape/logtape");
+let ai = require("ai");
+
+//#region src/refine.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"vertana",
+	"core",
+	"refine"
+]);
+/**
+* Gets the language name from a locale.
+*/
+function getLanguageName(locale) {
+	const tag = typeof locale === "string" ? locale : locale.baseName;
+	try {
+		return new Intl.DisplayNames(["en"], { type: "language" }).of(tag) ?? tag;
+	} catch {
+		return tag;
+	}
+}
+/**
+* Builds the system prompt for chunk refinement.
+*/
+function buildRefineSystemPrompt(options, issues) {
+	const targetLang = getLanguageName(options.targetLanguage);
+	let prompt = `You are an expert translator refining a translation from ${(options.sourceLanguage ? getLanguageName(options.sourceLanguage) : null) ?? "the source language"} to ${targetLang}.
+
+You will be given:
+1. The original text
+2. The current translation
+3. A list of issues found in the translation
+
+Your task is to fix the issues while preserving the parts that are correct.
+Output ONLY the improved translation, nothing else.
+
+## Issues to fix
+
+`;
+	for (const issue of issues) prompt += `- [${issue.type}] ${issue.description}\n`;
+	if (options.glossary != null && options.glossary.length > 0) {
+		prompt += `\n## Glossary (must follow exactly)\n\n`;
+		for (const entry of options.glossary) prompt += `- "${entry.original}" → "${entry.translated}"\n`;
+	}
+	return prompt;
+}
+/**
+* Builds the user prompt for chunk refinement.
+*/
+function buildRefineUserPrompt(original, translated) {
+	return `## Original Text
+
+${original}
+
+## Current Translation
+
+${translated}
+
+Please provide the improved translation:`;
+}
+/**
+* Refines a single chunk based on evaluation feedback.
+*/
+async function refineChunk(model, original, translated, issues, options) {
+	return (await (0, ai.generateText)({
+		model,
+		system: buildRefineSystemPrompt(options, issues),
+		prompt: buildRefineUserPrompt(original, translated),
+		abortSignal: options.signal
+	})).text.trim();
+}
+/**
+* Evaluates the boundary between two chunks for coherence.
+*/
+async function evaluateBoundary(model, chunk1Translated, chunk2Translated, chunk1Original, chunk2Original, options) {
+	const targetLang = getLanguageName(options.targetLanguage);
+	const boundarySize = 200;
+	const chunk1End = chunk1Translated.slice(-boundarySize);
+	const chunk2Start = chunk2Translated.slice(0, boundarySize);
+	const result = await (0, ai.generateText)({
+		model,
+		system: `You are an expert translation quality evaluator.
+
+Evaluate the coherence at the boundary between two consecutive translation chunks.
+
+Check for:
+1. **Coherence**: Does the text flow naturally from one chunk to the next?
+2. **Style**: Is the style consistent across the boundary?
+3. **Reference**: Are pronouns and references consistent?
+4. **Terminology**: Are terms used consistently?
+
+Respond in this exact JSON format:
+{
+  "score": <number between 0 and 1>,
+  "issues": [
+    {"type": "<coherence|style|reference|terminology>", "description": "<description>"}
+  ]
+}`,
+		prompt: `## End of chunk 1 (original)
+${chunk1Original.slice(-boundarySize)}
+
+## End of chunk 1 (translated to ${targetLang})
+${chunk1End}
+
+## Start of chunk 2 (original)
+${chunk2Original.slice(0, boundarySize)}
+
+## Start of chunk 2 (translated to ${targetLang})
+${chunk2Start}
+
+Evaluate the boundary coherence:`,
+		abortSignal: options.signal
+	});
+	try {
+		const parsed = JSON.parse(result.text);
+		return {
+			score: Math.max(0, Math.min(1, parsed.score)),
+			issues: parsed.issues ?? []
+		};
+	} catch {
+		return {
+			score: 1,
+			issues: []
+		};
+	}
+}
+/**
+* Refines translated chunks to improve quality using an iterative
+* evaluate-fix loop.
+*
+* @param model The language model to use for refinement.
+* @param originalChunks The original text chunks that were translated.
+* @param translatedChunks The translated chunks to refine.
+* @param options Refinement options.
+* @returns A promise that resolves to the refinement result.
+* @throws {RangeError} If the number of original and translated chunks
+*                      do not match.
+*/
+async function refineChunks(model, originalChunks, translatedChunks, options) {
+	if (originalChunks.length !== translatedChunks.length) throw new RangeError(`Chunk count mismatch: ${originalChunks.length} original vs ${translatedChunks.length} translated`);
+	const targetScore = options.targetScore ?? .85;
+	const maxIterations = options.maxIterations ?? 3;
+	const shouldEvaluateBoundaries = options.evaluateBoundaries ?? true;
+	logger.info("Starting refinement of {chunkCount} chunks...", {
+		chunkCount: originalChunks.length,
+		targetScore,
+		maxIterations
+	});
+	const refinedChunks = [...translatedChunks];
+	const scores = new Array(translatedChunks.length).fill(0);
+	const history = [];
+	let totalIterations = 0;
+	for (let i = 0; i < refinedChunks.length; i++) {
+		options.signal?.throwIfAborted();
+		logger.debug("Evaluating chunk {index} of {total}...", {
+			index: i + 1,
+			total: refinedChunks.length
+		});
+		let currentText = refinedChunks[i];
+		let evaluation;
+		evaluation = await require_evaluation.evaluate(model, originalChunks[i], currentText, {
+			targetLanguage: options.targetLanguage,
+			sourceLanguage: options.sourceLanguage,
+			glossary: options.glossary,
+			signal: options.signal
+		});
+		scores[i] = evaluation.score;
+		logger.debug("Chunk {index} initial score: {score}.", {
+			index: i + 1,
+			score: evaluation.score,
+			issues: evaluation.issues.length
+		});
+		let iteration = 0;
+		while (evaluation.score < targetScore && iteration < maxIterations) {
+			options.signal?.throwIfAborted();
+			iteration++;
+			totalIterations++;
+			const beforeText = currentText;
+			const scoreBefore = evaluation.score;
+			const issuesAddressed = evaluation.issues;
+			currentText = await refineChunk(model, originalChunks[i], currentText, evaluation.issues, options);
+			evaluation = await require_evaluation.evaluate(model, originalChunks[i], currentText, {
+				targetLanguage: options.targetLanguage,
+				sourceLanguage: options.sourceLanguage,
+				glossary: options.glossary,
+				signal: options.signal
+			});
+			history.push({
+				chunkIndex: i,
+				iteration,
+				before: beforeText,
+				after: currentText,
+				scoreBefore,
+				scoreAfter: evaluation.score,
+				issuesAddressed
+			});
+			logger.debug("Chunk {chunkIndex} iteration {iteration}: {scoreBefore} → {scoreAfter}.", {
+				chunkIndex: i + 1,
+				iteration,
+				scoreBefore,
+				scoreAfter: evaluation.score
+			});
+			scores[i] = evaluation.score;
+		}
+		refinedChunks[i] = currentText;
+	}
+	let boundaryEvaluations;
+	if (shouldEvaluateBoundaries && refinedChunks.length > 1) {
+		logger.debug("Evaluating {count} chunk boundaries...", { count: refinedChunks.length - 1 });
+		boundaryEvaluations = [];
+		for (let i = 0; i < refinedChunks.length - 1; i++) {
+			options.signal?.throwIfAborted();
+			const boundaryResult = await evaluateBoundary(model, refinedChunks[i], refinedChunks[i + 1], originalChunks[i], originalChunks[i + 1], options);
+			boundaryEvaluations.push({
+				chunkIndex: i,
+				...boundaryResult
+			});
+			if (boundaryResult.issues.length > 0) logger.warn("Boundary {index} has {issueCount} issue(s), score: {score}.", {
+				index: i + 1,
+				issueCount: boundaryResult.issues.length,
+				score: boundaryResult.score
+			});
+		}
+	}
+	const averageScore = scores.reduce((a, b) => a + b, 0) / scores.length;
+	logger.info("Refinement completed.", {
+		totalIterations,
+		averageScore,
+		chunkCount: refinedChunks.length
+	});
+	return {
+		chunks: refinedChunks,
+		scores,
+		totalIterations,
+		history,
+		boundaryEvaluations
+	};
+}
+
+//#endregion
+exports.evaluateBoundary = evaluateBoundary;
+exports.refineChunks = refineChunks;

package/dist/refine.d.cts

@@ -0,0 +1,148 @@
+import { Glossary } from "./glossary.cjs";
+import { TranslationIssue } from "./evaluation.cjs";
+import { LanguageModel } from "ai";
+
+//#region src/refine.d.ts
+
+/**
+ * Options for the {@link refineChunks} function.
+ */
+interface RefineChunksOptions {
+  /**
+   * The target language of the translation.
+   */
+  readonly targetLanguage: Intl.Locale | string;
+  /**
+   * The source language of the original text.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * The minimum acceptable quality score (0-1). Chunks with scores below
+   * this threshold will be refined. Defaults to 0.85.
+   */
+  readonly targetScore?: number;
+  /**
+   * Maximum number of refinement iterations per chunk. Defaults to 3.
+   */
+  readonly maxIterations?: number;
+  /**
+   * A glossary of terms that should be used consistently.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * Whether to evaluate boundaries between chunks for coherence.
+   * Defaults to true.
+   */
+  readonly evaluateBoundaries?: boolean;
+  /**
+   * An optional `AbortSignal` to cancel the refinement.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of evaluating a boundary between two chunks.
+ */
+interface BoundaryEvaluation {
+  /**
+   * Index of the first chunk in the boundary (chunk i and chunk i+1).
+   */
+  readonly chunkIndex: number;
+  /**
+   * A coherence score between 0 and 1.
+   */
+  readonly score: number;
+  /**
+   * Issues found at the boundary.
+   */
+  readonly issues: readonly BoundaryIssue[];
+}
+/**
+ * An issue found at a chunk boundary.
+ */
+interface BoundaryIssue {
+  /**
+   * The type of boundary issue.
+   */
+  readonly type: "coherence" | "style" | "reference" | "terminology";
+  /**
+   * A human-readable description of the issue.
+   */
+  readonly description: string;
+}
+/**
+ * Record of a single refinement iteration for a chunk.
+ */
+interface RefineIteration {
+  /**
+   * The chunk index that was refined.
+   */
+  readonly chunkIndex: number;
+  /**
+   * The iteration number (1-based).
+   */
+  readonly iteration: number;
+  /**
+   * The text before refinement.
+   */
+  readonly before: string;
+  /**
+   * The text after refinement.
+   */
+  readonly after: string;
+  /**
+   * The evaluation score before refinement.
+   */
+  readonly scoreBefore: number;
+  /**
+   * The evaluation score after refinement.
+   */
+  readonly scoreAfter: number;
+  /**
+   * Issues that were addressed in this iteration.
+   */
+  readonly issuesAddressed: readonly TranslationIssue[];
+}
+/**
+ * The result of the {@link refineChunks} function.
+ */
+interface RefineChunksResult {
+  /**
+   * The refined translated chunks.
+   */
+  readonly chunks: readonly string[];
+  /**
+   * Final evaluation scores for each chunk.
+   */
+  readonly scores: readonly number[];
+  /**
+   * Total number of refinement iterations performed.
+   */
+  readonly totalIterations: number;
+  /**
+   * History of all refinement iterations.
+   */
+  readonly history: readonly RefineIteration[];
+  /**
+   * Boundary evaluations (if evaluateBoundaries was enabled).
+   */
+  readonly boundaryEvaluations?: readonly BoundaryEvaluation[];
+}
+/**
+ * Evaluates the boundary between two chunks for coherence.
+ */
+declare function evaluateBoundary(model: LanguageModel, chunk1Translated: string, chunk2Translated: string, chunk1Original: string, chunk2Original: string, options: RefineChunksOptions): Promise<Omit<BoundaryEvaluation, "chunkIndex">>;
+/**
+ * Refines translated chunks to improve quality using an iterative
+ * evaluate-fix loop.
+ *
+ * @param model The language model to use for refinement.
+ * @param originalChunks The original text chunks that were translated.
+ * @param translatedChunks The translated chunks to refine.
+ * @param options Refinement options.
+ * @returns A promise that resolves to the refinement result.
+ * @throws {RangeError} If the number of original and translated chunks
+ *                      do not match.
+ */
+declare function refineChunks(model: LanguageModel, originalChunks: readonly string[], translatedChunks: readonly string[], options: RefineChunksOptions): Promise<RefineChunksResult>;
+//#endregion
+export { BoundaryEvaluation, BoundaryIssue, RefineChunksOptions, RefineChunksResult, RefineIteration, evaluateBoundary, refineChunks };

package/dist/refine.d.ts

@@ -0,0 +1,148 @@
+import { Glossary } from "./glossary.js";
+import { TranslationIssue } from "./evaluation.js";
+import { LanguageModel } from "ai";
+
+//#region src/refine.d.ts
+
+/**
+ * Options for the {@link refineChunks} function.
+ */
+interface RefineChunksOptions {
+  /**
+   * The target language of the translation.
+   */
+  readonly targetLanguage: Intl.Locale | string;
+  /**
+   * The source language of the original text.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * The minimum acceptable quality score (0-1). Chunks with scores below
+   * this threshold will be refined. Defaults to 0.85.
+   */
+  readonly targetScore?: number;
+  /**
+   * Maximum number of refinement iterations per chunk. Defaults to 3.
+   */
+  readonly maxIterations?: number;
+  /**
+   * A glossary of terms that should be used consistently.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * Whether to evaluate boundaries between chunks for coherence.
+   * Defaults to true.
+   */
+  readonly evaluateBoundaries?: boolean;
+  /**
+   * An optional `AbortSignal` to cancel the refinement.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of evaluating a boundary between two chunks.
+ */
+interface BoundaryEvaluation {
+  /**
+   * Index of the first chunk in the boundary (chunk i and chunk i+1).
+   */
+  readonly chunkIndex: number;
+  /**
+   * A coherence score between 0 and 1.
+   */
+  readonly score: number;
+  /**
+   * Issues found at the boundary.
+   */
+  readonly issues: readonly BoundaryIssue[];
+}
+/**
+ * An issue found at a chunk boundary.
+ */
+interface BoundaryIssue {
+  /**
+   * The type of boundary issue.
+   */
+  readonly type: "coherence" | "style" | "reference" | "terminology";
+  /**
+   * A human-readable description of the issue.
+   */
+  readonly description: string;
+}
+/**
+ * Record of a single refinement iteration for a chunk.
+ */
+interface RefineIteration {
+  /**
+   * The chunk index that was refined.
+   */
+  readonly chunkIndex: number;
+  /**
+   * The iteration number (1-based).
+   */
+  readonly iteration: number;
+  /**
+   * The text before refinement.
+   */
+  readonly before: string;
+  /**
+   * The text after refinement.
+   */
+  readonly after: string;
+  /**
+   * The evaluation score before refinement.
+   */
+  readonly scoreBefore: number;
+  /**
+   * The evaluation score after refinement.
+   */
+  readonly scoreAfter: number;
+  /**
+   * Issues that were addressed in this iteration.
+   */
+  readonly issuesAddressed: readonly TranslationIssue[];
+}
+/**
+ * The result of the {@link refineChunks} function.
+ */
+interface RefineChunksResult {
+  /**
+   * The refined translated chunks.
+   */
+  readonly chunks: readonly string[];
+  /**
+   * Final evaluation scores for each chunk.
+   */
+  readonly scores: readonly number[];
+  /**
+   * Total number of refinement iterations performed.
+   */
+  readonly totalIterations: number;
+  /**
+   * History of all refinement iterations.
+   */
+  readonly history: readonly RefineIteration[];
+  /**
+   * Boundary evaluations (if evaluateBoundaries was enabled).
+   */
+  readonly boundaryEvaluations?: readonly BoundaryEvaluation[];
+}
+/**
+ * Evaluates the boundary between two chunks for coherence.
+ */
+declare function evaluateBoundary(model: LanguageModel, chunk1Translated: string, chunk2Translated: string, chunk1Original: string, chunk2Original: string, options: RefineChunksOptions): Promise<Omit<BoundaryEvaluation, "chunkIndex">>;
+/**
+ * Refines translated chunks to improve quality using an iterative
+ * evaluate-fix loop.
+ *
+ * @param model The language model to use for refinement.
+ * @param originalChunks The original text chunks that were translated.
+ * @param translatedChunks The translated chunks to refine.
+ * @param options Refinement options.
+ * @returns A promise that resolves to the refinement result.
+ * @throws {RangeError} If the number of original and translated chunks
+ *                      do not match.
+ */
+declare function refineChunks(model: LanguageModel, originalChunks: readonly string[], translatedChunks: readonly string[], options: RefineChunksOptions): Promise<RefineChunksResult>;
+//#endregion
+export { BoundaryEvaluation, BoundaryIssue, RefineChunksOptions, RefineChunksResult, RefineIteration, evaluateBoundary, refineChunks };