@vertana/core 0.1.0-dev.1

package/dist/refine.js

@@ -0,0 +1,241 @@
+import { evaluate } from "./evaluation.js";
+import { getLogger } from "@logtape/logtape";
+import { generateText } from "ai";
+
+//#region src/refine.ts
+const logger = 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 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 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 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 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
+export { evaluateBoundary, refineChunks };

package/dist/select.cjs

@@ -0,0 +1,62 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_evaluation = require('./evaluation.cjs');
+let _logtape_logtape = require("@logtape/logtape");
+
+//#region src/select.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"vertana",
+	"core",
+	"select"
+]);
+/**
+* Evaluates multiple translation candidates and selects the best one.
+*
+* @param evaluatorModel The language model to use for evaluation.
+* @param original The original text that was translated.
+* @param candidates The translation candidates to evaluate.
+* @param options Selection options.
+* @returns A promise that resolves to the selection result.
+* @throws {RangeError} If no candidates are provided.
+*/
+async function selectBest(evaluatorModel, original, candidates, options) {
+	if (candidates.length === 0) throw new RangeError("At least one candidate is required.");
+	logger.debug("Selecting best from {count} candidates...", { count: candidates.length });
+	const evaluatedCandidates = [];
+	for (const candidate of candidates) {
+		options.signal?.throwIfAborted();
+		const evaluation = await require_evaluation.evaluate(evaluatorModel, original, candidate.text, {
+			targetLanguage: options.targetLanguage,
+			sourceLanguage: options.sourceLanguage,
+			glossary: options.glossary,
+			signal: options.signal
+		});
+		evaluatedCandidates.push({
+			candidate,
+			score: evaluation.score,
+			issues: evaluation.issues
+		});
+		logger.debug("Candidate {index} score: {score}.", {
+			index: evaluatedCandidates.length,
+			score: evaluation.score,
+			issues: evaluation.issues.length
+		});
+	}
+	const rankedCandidates = [...evaluatedCandidates].sort((a, b) => b.score - a.score).map((item, index) => ({
+		text: item.candidate.text,
+		metadata: item.candidate.metadata,
+		score: item.score,
+		issues: item.issues,
+		rank: index + 1
+	}));
+	logger.debug("Selected best candidate with score: {score}.", {
+		score: rankedCandidates[0].score,
+		totalCandidates: candidates.length
+	});
+	return {
+		best: rankedCandidates[0],
+		all: rankedCandidates
+	};
+}
+
+//#endregion
+exports.selectBest = selectBest;

package/dist/select.d.cts

@@ -0,0 +1,83 @@
+import { Glossary } from "./glossary.cjs";
+import { TranslationIssue } from "./evaluation.cjs";
+import { LanguageModel } from "ai";
+
+//#region src/select.d.ts
+
+/**
+ * A translation candidate to be evaluated.
+ */
+interface Candidate<T = unknown> {
+  /**
+   * The translated text.
+   */
+  readonly text: string;
+  /**
+   * Optional metadata associated with this candidate (e.g., model info).
+   */
+  readonly metadata?: T;
+}
+/**
+ * A candidate with evaluation results and ranking.
+ */
+interface RankedCandidate<T = unknown> extends Candidate<T> {
+  /**
+   * The evaluation score (0-1).
+   */
+  readonly score: number;
+  /**
+   * Issues found in the translation.
+   */
+  readonly issues: readonly TranslationIssue[];
+  /**
+   * The rank of this candidate (1-based, 1 is best).
+   */
+  readonly rank: number;
+}
+/**
+ * Options for the {@link selectBest} function.
+ */
+interface SelectBestOptions {
+  /**
+   * The target language of the translation.
+   */
+  readonly targetLanguage: Intl.Locale | string;
+  /**
+   * The source language of the original text.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * A glossary of terms that should be used consistently.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * An optional `AbortSignal` to cancel the selection.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of the {@link selectBest} function.
+ */
+interface SelectBestResult<T = unknown> {
+  /**
+   * The best candidate based on evaluation scores.
+   */
+  readonly best: RankedCandidate<T>;
+  /**
+   * All candidates with their evaluation results, sorted by rank.
+   */
+  readonly all: readonly RankedCandidate<T>[];
+}
+/**
+ * Evaluates multiple translation candidates and selects the best one.
+ *
+ * @param evaluatorModel The language model to use for evaluation.
+ * @param original The original text that was translated.
+ * @param candidates The translation candidates to evaluate.
+ * @param options Selection options.
+ * @returns A promise that resolves to the selection result.
+ * @throws {RangeError} If no candidates are provided.
+ */
+declare function selectBest<T = unknown>(evaluatorModel: LanguageModel, original: string, candidates: readonly Candidate<T>[], options: SelectBestOptions): Promise<SelectBestResult<T>>;
+//#endregion
+export { Candidate, RankedCandidate, SelectBestOptions, SelectBestResult, selectBest };

package/dist/select.d.ts

@@ -0,0 +1,83 @@
+import { Glossary } from "./glossary.js";
+import { TranslationIssue } from "./evaluation.js";
+import { LanguageModel } from "ai";
+
+//#region src/select.d.ts
+
+/**
+ * A translation candidate to be evaluated.
+ */
+interface Candidate<T = unknown> {
+  /**
+   * The translated text.
+   */
+  readonly text: string;
+  /**
+   * Optional metadata associated with this candidate (e.g., model info).
+   */
+  readonly metadata?: T;
+}
+/**
+ * A candidate with evaluation results and ranking.
+ */
+interface RankedCandidate<T = unknown> extends Candidate<T> {
+  /**
+   * The evaluation score (0-1).
+   */
+  readonly score: number;
+  /**
+   * Issues found in the translation.
+   */
+  readonly issues: readonly TranslationIssue[];
+  /**
+   * The rank of this candidate (1-based, 1 is best).
+   */
+  readonly rank: number;
+}
+/**
+ * Options for the {@link selectBest} function.
+ */
+interface SelectBestOptions {
+  /**
+   * The target language of the translation.
+   */
+  readonly targetLanguage: Intl.Locale | string;
+  /**
+   * The source language of the original text.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * A glossary of terms that should be used consistently.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * An optional `AbortSignal` to cancel the selection.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of the {@link selectBest} function.
+ */
+interface SelectBestResult<T = unknown> {
+  /**
+   * The best candidate based on evaluation scores.
+   */
+  readonly best: RankedCandidate<T>;
+  /**
+   * All candidates with their evaluation results, sorted by rank.
+   */
+  readonly all: readonly RankedCandidate<T>[];
+}
+/**
+ * Evaluates multiple translation candidates and selects the best one.
+ *
+ * @param evaluatorModel The language model to use for evaluation.
+ * @param original The original text that was translated.
+ * @param candidates The translation candidates to evaluate.
+ * @param options Selection options.
+ * @returns A promise that resolves to the selection result.
+ * @throws {RangeError} If no candidates are provided.
+ */
+declare function selectBest<T = unknown>(evaluatorModel: LanguageModel, original: string, candidates: readonly Candidate<T>[], options: SelectBestOptions): Promise<SelectBestResult<T>>;
+//#endregion
+export { Candidate, RankedCandidate, SelectBestOptions, SelectBestResult, selectBest };

package/dist/select.js

@@ -0,0 +1,61 @@
+import { evaluate } from "./evaluation.js";
+import { getLogger } from "@logtape/logtape";
+
+//#region src/select.ts
+const logger = getLogger([
+	"vertana",
+	"core",
+	"select"
+]);
+/**
+* Evaluates multiple translation candidates and selects the best one.
+*
+* @param evaluatorModel The language model to use for evaluation.
+* @param original The original text that was translated.
+* @param candidates The translation candidates to evaluate.
+* @param options Selection options.
+* @returns A promise that resolves to the selection result.
+* @throws {RangeError} If no candidates are provided.
+*/
+async function selectBest(evaluatorModel, original, candidates, options) {
+	if (candidates.length === 0) throw new RangeError("At least one candidate is required.");
+	logger.debug("Selecting best from {count} candidates...", { count: candidates.length });
+	const evaluatedCandidates = [];
+	for (const candidate of candidates) {
+		options.signal?.throwIfAborted();
+		const evaluation = await evaluate(evaluatorModel, original, candidate.text, {
+			targetLanguage: options.targetLanguage,
+			sourceLanguage: options.sourceLanguage,
+			glossary: options.glossary,
+			signal: options.signal
+		});
+		evaluatedCandidates.push({
+			candidate,
+			score: evaluation.score,
+			issues: evaluation.issues
+		});
+		logger.debug("Candidate {index} score: {score}.", {
+			index: evaluatedCandidates.length,
+			score: evaluation.score,
+			issues: evaluation.issues.length
+		});
+	}
+	const rankedCandidates = [...evaluatedCandidates].sort((a, b) => b.score - a.score).map((item, index) => ({
+		text: item.candidate.text,
+		metadata: item.candidate.metadata,
+		score: item.score,
+		issues: item.issues,
+		rank: index + 1
+	}));
+	logger.debug("Selected best candidate with score: {score}.", {
+		score: rankedCandidates[0].score,
+		totalCandidates: candidates.length
+	});
+	return {
+		best: rankedCandidates[0],
+		all: rankedCandidates
+	};
+}
+
+//#endregion
+export { selectBest };

package/dist/terms.cjs

@@ -0,0 +1,60 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let ai = require("ai");
+let zod = require("zod");
+
+//#region src/terms.ts
+/**
+* Schema for extracted terms.
+*/
+const extractedTermsSchema = zod.z.object({ terms: zod.z.array(zod.z.object({
+	original: zod.z.string().describe("The original term in the source text"),
+	translated: zod.z.string().describe("The translated term"),
+	context: zod.z.string().optional().describe("Optional context for when to use this translation")
+})) });
+/**
+* Extracts key terminology pairs from source text and its translation.
+*
+* This function uses an LLM to identify important terms, proper nouns,
+* technical vocabulary, and other key phrases that should be translated
+* consistently throughout a document.
+*
+* @param model The language model to use for extraction.
+* @param sourceText The original source text.
+* @param translatedText The translated text.
+* @param options Optional extraction options.
+* @returns An array of glossary entries.
+*/
+async function extractTerms(model, sourceText, translatedText, options) {
+	const maxTerms = options?.maxTerms ?? 10;
+	const signal = options?.signal;
+	signal?.throwIfAborted();
+	return (await (0, ai.generateObject)({
+		model,
+		schema: extractedTermsSchema,
+		system: `You are a terminology extraction expert. Your task is to identify key terms from a source text and its translation that should be translated consistently.
+
+Focus on extracting:
+- Technical terms and domain-specific vocabulary
+- Proper nouns (names, organizations, products)
+- Key concepts and phrases
+- Terms that appear multiple times or are central to the meaning
+
+Do NOT extract:
+- Common words that don't need consistent translation
+- Function words (articles, prepositions, conjunctions)
+- Terms that are already well-known in both languages
+
+Extract at most ${maxTerms} of the most important terms.`,
+		prompt: `Source text:
+${sourceText}
+
+Translated text:
+${translatedText}
+
+Extract the key terminology pairs from the above texts.`,
+		abortSignal: signal
+	})).object.terms.slice(0, maxTerms);
+}
+
+//#endregion
+exports.extractTerms = extractTerms;

package/dist/terms.d.cts

@@ -0,0 +1,36 @@
+import { GlossaryEntry } from "./glossary.cjs";
+import { LanguageModel } from "ai";
+
+//#region src/terms.d.ts
+
+/**
+ * Options for extracting terms from a translation.
+ */
+interface ExtractTermsOptions {
+  /**
+   * Maximum number of terms to extract.
+   *
+   * @default `10`
+   */
+  readonly maxTerms?: number;
+  /**
+   * Optional abort signal.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Extracts key terminology pairs from source text and its translation.
+ *
+ * This function uses an LLM to identify important terms, proper nouns,
+ * technical vocabulary, and other key phrases that should be translated
+ * consistently throughout a document.
+ *
+ * @param model The language model to use for extraction.
+ * @param sourceText The original source text.
+ * @param translatedText The translated text.
+ * @param options Optional extraction options.
+ * @returns An array of glossary entries.
+ */
+declare function extractTerms(model: LanguageModel, sourceText: string, translatedText: string, options?: ExtractTermsOptions): Promise<readonly GlossaryEntry[]>;
+//#endregion
+export { ExtractTermsOptions, extractTerms };

package/dist/terms.d.ts

@@ -0,0 +1,36 @@
+import { GlossaryEntry } from "./glossary.js";
+import { LanguageModel } from "ai";
+
+//#region src/terms.d.ts
+
+/**
+ * Options for extracting terms from a translation.
+ */
+interface ExtractTermsOptions {
+  /**
+   * Maximum number of terms to extract.
+   *
+   * @default `10`
+   */
+  readonly maxTerms?: number;
+  /**
+   * Optional abort signal.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Extracts key terminology pairs from source text and its translation.
+ *
+ * This function uses an LLM to identify important terms, proper nouns,
+ * technical vocabulary, and other key phrases that should be translated
+ * consistently throughout a document.
+ *
+ * @param model The language model to use for extraction.
+ * @param sourceText The original source text.
+ * @param translatedText The translated text.
+ * @param options Optional extraction options.
+ * @returns An array of glossary entries.
+ */
+declare function extractTerms(model: LanguageModel, sourceText: string, translatedText: string, options?: ExtractTermsOptions): Promise<readonly GlossaryEntry[]>;
+//#endregion
+export { ExtractTermsOptions, extractTerms };