@vertana/core 0.1.0-dev.1

package/dist/context.cjs

@@ -0,0 +1,51 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _logtape_logtape = require("@logtape/logtape");
+
+//#region src/context.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"vertana",
+	"core",
+	"context"
+]);
+/**
+* Gathers context from all required context sources.
+*
+* @param sources The context sources to gather from.
+* @param signal An optional abort signal to cancel the operation.
+* @returns A promise that resolves to the gathered context results.
+*/
+async function gatherRequiredContext(sources, signal) {
+	const requiredSources = sources.filter((s) => s.mode === "required");
+	if (requiredSources.length === 0) return [];
+	logger.info("Gathering context from {count} required source(s)...", { count: requiredSources.length });
+	const results = [];
+	for (const source of requiredSources) {
+		signal?.throwIfAborted();
+		logger.debug("Gathering context from source: {name}...", { name: source.name });
+		const result = await source.gather({ signal });
+		results.push(result);
+	}
+	logger.info("Context gathering completed.", {
+		sourceCount: requiredSources.length,
+		totalContentLength: results.reduce((sum, r) => sum + r.content.length, 0)
+	});
+	return results;
+}
+/**
+* Combines gathered context results into a single string.
+*
+* @param results The context results to combine.
+* @returns The combined context as a single string.
+*/
+function combineContextResults(results) {
+	const combined = results.map((r) => r.content).filter((c) => c.trim().length > 0).join("\n\n");
+	logger.debug("Combined {count} context result(s) into {length} characters.", {
+		count: results.length,
+		length: combined.length
+	});
+	return combined;
+}
+
+//#endregion
+exports.combineContextResults = combineContextResults;
+exports.gatherRequiredContext = gatherRequiredContext;

package/dist/context.d.cts

@@ -0,0 +1,148 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/context.d.ts
+
+/**
+ * Options for the {@link ContextSource.gather} method.
+ */
+interface ContextSourceGatherOptions {
+  /**
+   * An optional `AbortSignal` to cancel the context gathering operation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of gathering context from a {@link ContextSource}.
+ */
+interface ContextResult {
+  /**
+   * The gathered context content as a string.
+   */
+  readonly content: string;
+  /**
+   * Optional metadata about the gathered context.
+   */
+  readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Base properties shared by all context sources.
+ */
+interface ContextSourceBase {
+  /**
+   * A unique identifier for the context source.
+   */
+  readonly name: string;
+  /**
+   * A human-readable description of what this context source provides.
+   * For passive sources, this description helps the LLM decide when to use it.
+   */
+  readonly description: string;
+}
+/**
+ * A context source that is automatically invoked during the translation
+ * pipeline.  Required sources are always executed before translation begins.
+ */
+interface RequiredContextSource extends ContextSourceBase {
+  /**
+   * Indicates that this source is always invoked.
+   */
+  readonly mode: "required";
+  /**
+   * Gathers context.  Called automatically during the translation pipeline.
+   *
+   * @param options Optional settings for the gathering operation.
+   * @returns A promise that resolves to the gathered context.
+   */
+  gather(options?: ContextSourceGatherOptions): Promise<ContextResult>;
+}
+/**
+ * A context source that can be invoked by the LLM agent when needed.
+ * Passive sources are exposed as tools that the agent can choose to call.
+ *
+ * @typeParam TParams The type of parameters accepted by the {@link gather}
+ *                    method.
+ */
+interface PassiveContextSource<TParams> extends ContextSourceBase {
+  /**
+   * Indicates that this source is invoked by the LLM agent on demand.
+   */
+  readonly mode: "passive";
+  /**
+   * A Standard Schema defining the parameters for the {@link gather} method.
+   * This schema is used to generate the tool definition for the LLM.
+   */
+  readonly parameters: StandardSchemaV1<TParams>;
+  /**
+   * Gathers context based on the provided parameters.
+   *
+   * @param params The parameters for gathering context, validated against
+   *               the {@link parameters} schema.
+   * @param options Optional settings for the gathering operation.
+   * @returns A promise that resolves to the gathered context.
+   */
+  gather(params: TParams, options?: ContextSourceGatherOptions): Promise<ContextResult>;
+}
+/**
+ * A source that provides additional context for translation.
+ *
+ * Context sources can operate in two modes:
+ *
+ * - `"required"`: Always invoked at the start of the translation pipeline.
+ *   Use this for context that is essential for every translation, such as
+ *   author biography or document metadata.
+ *
+ * - `"passive"`: Exposed as a tool that the LLM agent can invoke on demand.
+ *   Use this for context that may or may not be needed, such as fetching
+ *   linked articles or looking up terminology.
+ *
+ * @typeParam TParams The type of parameters for passive sources.
+ */
+type ContextSource<TParams = unknown> = RequiredContextSource | PassiveContextSource<TParams>;
+/**
+ * A factory function that creates a {@link ContextSource}.
+ *
+ * Factory functions are the recommended way to create context sources,
+ * as they allow for configuration validation and dependency injection.
+ *
+ * @typeParam TOptions The type of options accepted by the factory.
+ * @typeParam TParams The type of parameters for passive sources.
+ * @param options Configuration options for the context source.
+ * @returns A configured context source.
+ *
+ * @example Create a factory for fetching author information
+ * ```typescript
+ * interface AuthorBioOptions {
+ *   readonly authorId: string;
+ *   readonly fetchBio: (id: string) => Promise<string>;
+ * }
+ *
+ * const createAuthorBioSource: ContextSourceFactory<AuthorBioOptions> =
+ *   (options) => ({
+ *     name: "author-bio",
+ *     description: "Fetches the author's biography for context",
+ *     mode: "required",
+ *     async gather(gatherOptions) {
+ *       const bio = await options.fetchBio(options.authorId, gatherOptions);
+ *       return { content: bio };
+ *     },
+ *   });
+ * ```
+ */
+type ContextSourceFactory<TOptions, TParams = unknown> = (options: TOptions) => ContextSource<TParams>;
+/**
+ * Gathers context from all required context sources.
+ *
+ * @param sources The context sources to gather from.
+ * @param signal An optional abort signal to cancel the operation.
+ * @returns A promise that resolves to the gathered context results.
+ */
+declare function gatherRequiredContext(sources: readonly ContextSource[], signal?: AbortSignal): Promise<readonly ContextResult[]>;
+/**
+ * Combines gathered context results into a single string.
+ *
+ * @param results The context results to combine.
+ * @returns The combined context as a single string.
+ */
+declare function combineContextResults(results: readonly ContextResult[]): string;
+//#endregion
+export { ContextResult, ContextSource, ContextSourceFactory, ContextSourceGatherOptions, PassiveContextSource, RequiredContextSource, combineContextResults, gatherRequiredContext };

package/dist/context.d.ts

@@ -0,0 +1,148 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/context.d.ts
+
+/**
+ * Options for the {@link ContextSource.gather} method.
+ */
+interface ContextSourceGatherOptions {
+  /**
+   * An optional `AbortSignal` to cancel the context gathering operation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The result of gathering context from a {@link ContextSource}.
+ */
+interface ContextResult {
+  /**
+   * The gathered context content as a string.
+   */
+  readonly content: string;
+  /**
+   * Optional metadata about the gathered context.
+   */
+  readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Base properties shared by all context sources.
+ */
+interface ContextSourceBase {
+  /**
+   * A unique identifier for the context source.
+   */
+  readonly name: string;
+  /**
+   * A human-readable description of what this context source provides.
+   * For passive sources, this description helps the LLM decide when to use it.
+   */
+  readonly description: string;
+}
+/**
+ * A context source that is automatically invoked during the translation
+ * pipeline.  Required sources are always executed before translation begins.
+ */
+interface RequiredContextSource extends ContextSourceBase {
+  /**
+   * Indicates that this source is always invoked.
+   */
+  readonly mode: "required";
+  /**
+   * Gathers context.  Called automatically during the translation pipeline.
+   *
+   * @param options Optional settings for the gathering operation.
+   * @returns A promise that resolves to the gathered context.
+   */
+  gather(options?: ContextSourceGatherOptions): Promise<ContextResult>;
+}
+/**
+ * A context source that can be invoked by the LLM agent when needed.
+ * Passive sources are exposed as tools that the agent can choose to call.
+ *
+ * @typeParam TParams The type of parameters accepted by the {@link gather}
+ *                    method.
+ */
+interface PassiveContextSource<TParams> extends ContextSourceBase {
+  /**
+   * Indicates that this source is invoked by the LLM agent on demand.
+   */
+  readonly mode: "passive";
+  /**
+   * A Standard Schema defining the parameters for the {@link gather} method.
+   * This schema is used to generate the tool definition for the LLM.
+   */
+  readonly parameters: StandardSchemaV1<TParams>;
+  /**
+   * Gathers context based on the provided parameters.
+   *
+   * @param params The parameters for gathering context, validated against
+   *               the {@link parameters} schema.
+   * @param options Optional settings for the gathering operation.
+   * @returns A promise that resolves to the gathered context.
+   */
+  gather(params: TParams, options?: ContextSourceGatherOptions): Promise<ContextResult>;
+}
+/**
+ * A source that provides additional context for translation.
+ *
+ * Context sources can operate in two modes:
+ *
+ * - `"required"`: Always invoked at the start of the translation pipeline.
+ *   Use this for context that is essential for every translation, such as
+ *   author biography or document metadata.
+ *
+ * - `"passive"`: Exposed as a tool that the LLM agent can invoke on demand.
+ *   Use this for context that may or may not be needed, such as fetching
+ *   linked articles or looking up terminology.
+ *
+ * @typeParam TParams The type of parameters for passive sources.
+ */
+type ContextSource<TParams = unknown> = RequiredContextSource | PassiveContextSource<TParams>;
+/**
+ * A factory function that creates a {@link ContextSource}.
+ *
+ * Factory functions are the recommended way to create context sources,
+ * as they allow for configuration validation and dependency injection.
+ *
+ * @typeParam TOptions The type of options accepted by the factory.
+ * @typeParam TParams The type of parameters for passive sources.
+ * @param options Configuration options for the context source.
+ * @returns A configured context source.
+ *
+ * @example Create a factory for fetching author information
+ * ```typescript
+ * interface AuthorBioOptions {
+ *   readonly authorId: string;
+ *   readonly fetchBio: (id: string) => Promise<string>;
+ * }
+ *
+ * const createAuthorBioSource: ContextSourceFactory<AuthorBioOptions> =
+ *   (options) => ({
+ *     name: "author-bio",
+ *     description: "Fetches the author's biography for context",
+ *     mode: "required",
+ *     async gather(gatherOptions) {
+ *       const bio = await options.fetchBio(options.authorId, gatherOptions);
+ *       return { content: bio };
+ *     },
+ *   });
+ * ```
+ */
+type ContextSourceFactory<TOptions, TParams = unknown> = (options: TOptions) => ContextSource<TParams>;
+/**
+ * Gathers context from all required context sources.
+ *
+ * @param sources The context sources to gather from.
+ * @param signal An optional abort signal to cancel the operation.
+ * @returns A promise that resolves to the gathered context results.
+ */
+declare function gatherRequiredContext(sources: readonly ContextSource[], signal?: AbortSignal): Promise<readonly ContextResult[]>;
+/**
+ * Combines gathered context results into a single string.
+ *
+ * @param results The context results to combine.
+ * @returns The combined context as a single string.
+ */
+declare function combineContextResults(results: readonly ContextResult[]): string;
+//#endregion
+export { ContextResult, ContextSource, ContextSourceFactory, ContextSourceGatherOptions, PassiveContextSource, RequiredContextSource, combineContextResults, gatherRequiredContext };

package/dist/context.js

@@ -0,0 +1,49 @@
+import { getLogger } from "@logtape/logtape";
+
+//#region src/context.ts
+const logger = getLogger([
+	"vertana",
+	"core",
+	"context"
+]);
+/**
+* Gathers context from all required context sources.
+*
+* @param sources The context sources to gather from.
+* @param signal An optional abort signal to cancel the operation.
+* @returns A promise that resolves to the gathered context results.
+*/
+async function gatherRequiredContext(sources, signal) {
+	const requiredSources = sources.filter((s) => s.mode === "required");
+	if (requiredSources.length === 0) return [];
+	logger.info("Gathering context from {count} required source(s)...", { count: requiredSources.length });
+	const results = [];
+	for (const source of requiredSources) {
+		signal?.throwIfAborted();
+		logger.debug("Gathering context from source: {name}...", { name: source.name });
+		const result = await source.gather({ signal });
+		results.push(result);
+	}
+	logger.info("Context gathering completed.", {
+		sourceCount: requiredSources.length,
+		totalContentLength: results.reduce((sum, r) => sum + r.content.length, 0)
+	});
+	return results;
+}
+/**
+* Combines gathered context results into a single string.
+*
+* @param results The context results to combine.
+* @returns The combined context as a single string.
+*/
+function combineContextResults(results) {
+	const combined = results.map((r) => r.content).filter((c) => c.trim().length > 0).join("\n\n");
+	logger.debug("Combined {count} context result(s) into {length} characters.", {
+		count: results.length,
+		length: combined.length
+	});
+	return combined;
+}
+
+//#endregion
+export { combineContextResults, gatherRequiredContext };

package/dist/evaluation.cjs

@@ -0,0 +1,120 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _logtape_logtape = require("@logtape/logtape");
+let ai = require("ai");
+let zod = require("zod");
+
+//#region src/evaluation.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"vertana",
+	"core",
+	"evaluate"
+]);
+const issueTypeSchema = zod.z.enum([
+	"accuracy",
+	"fluency",
+	"terminology",
+	"style"
+]);
+const issueSchema = zod.z.object({
+	type: issueTypeSchema,
+	description: zod.z.string(),
+	location: zod.z.object({
+		start: zod.z.number(),
+		end: zod.z.number()
+	}).optional()
+});
+const evaluationResultSchema = zod.z.object({
+	score: zod.z.number().min(0).max(1),
+	issues: zod.z.array(issueSchema)
+});
+/**
+* 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 evaluation.
+*/
+function buildEvaluationSystemPrompt(options) {
+	const targetLang = getLanguageName(options.targetLanguage);
+	let prompt = `You are an expert translation quality evaluator.
+
+Your task is to evaluate the quality of a translation from ${(options.sourceLanguage ? getLanguageName(options.sourceLanguage) : null) ?? "the source language"} to ${targetLang}.
+
+Evaluate the translation based on these criteria:
+
+1. **Accuracy**: Does the translation accurately convey the meaning of the original text?
+2. **Fluency**: Is the translation natural and readable in ${targetLang}?
+3. **Terminology**: Are domain-specific terms translated correctly and consistently?
+4. **Style**: Does the translation maintain the appropriate tone and style?
+
+Provide:
+- A score from 0 to 1 (where 1 is perfect, 0.9+ is excellent, 0.7-0.9 is good, 0.5-0.7 is acceptable, below 0.5 is poor)
+- A list of specific issues found, if any
+
+Be strict but fair in your evaluation. Minor issues should result in small deductions, while major meaning errors should significantly lower the score.`;
+	if (options.glossary != null && options.glossary.length > 0) {
+		prompt += `\n\n## Glossary
+
+The following terms MUST be translated as specified. Violations should be marked as "terminology" issues:
+
+`;
+		for (const entry of options.glossary) prompt += `- "${entry.original}" → "${entry.translated}"\n`;
+	}
+	return prompt;
+}
+/**
+* Builds the user prompt for evaluation.
+*/
+function buildEvaluationUserPrompt(original, translated) {
+	return `## Original Text
+
+${original}
+
+## Translated Text
+
+${translated}
+
+Please evaluate this translation.`;
+}
+/**
+* Evaluates the quality of a translation using an LLM.
+*
+* @param model The language model to use for evaluation.
+* @param original The original text that was translated.
+* @param translated The translated text to evaluate.
+* @param options Evaluation options including target language.
+* @returns A promise that resolves to the evaluation result.
+*/
+async function evaluate(model, original, translated, options) {
+	logger.debug("Evaluating translation quality...");
+	const result = await (0, ai.generateObject)({
+		model,
+		schema: evaluationResultSchema,
+		system: buildEvaluationSystemPrompt(options),
+		prompt: buildEvaluationUserPrompt(original, translated),
+		abortSignal: options.signal
+	});
+	const issues = result.object.issues.map((issue) => ({
+		type: issue.type,
+		description: issue.description,
+		location: issue.location
+	}));
+	logger.debug("Evaluation result: score {score}, {issueCount} issue(s).", {
+		score: result.object.score,
+		issueCount: issues.length
+	});
+	return {
+		score: result.object.score,
+		issues
+	};
+}
+
+//#endregion
+exports.evaluate = evaluate;

package/dist/evaluation.d.cts

@@ -0,0 +1,111 @@
+import { Glossary } from "./glossary.cjs";
+import { LanguageModel } from "ai";
+
+//#region src/evaluation.d.ts
+
+/**
+ * Options for {@link TranslationEvaluator}.
+ */
+interface EvaluatorOptions {
+  /**
+   * An optional `AbortSignal` to cancel the evaluation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Options for the {@link evaluate} function.
+ */
+interface EvaluateOptions {
+  /**
+   * 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 evaluation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Evaluates the quality of a translation.
+ *
+ * @param original The original text that was translated.
+ * @param translated The translated text to evaluate.
+ * @param options Optional settings for the evaluation.
+ * @returns A promise that resolves to the evaluation result.
+ */
+type TranslationEvaluator = (original: string, translated: string, options?: EvaluatorOptions) => Promise<EvaluationResult>;
+/**
+ * The result of evaluating a translation.
+ */
+interface EvaluationResult {
+  /**
+   * A quality score between 0 and 1, where 1 indicates a perfect translation
+   * and 0 indicates a completely incorrect translation.
+   */
+  readonly score: number;
+  /**
+   * Specific issues found in the translation.
+   */
+  readonly issues: readonly TranslationIssue[];
+}
+/**
+ * The type of issue found in a translation.
+ *
+ * - `"accuracy"`: The translation does not accurately convey the meaning
+ *   of the original text.
+ * - `"fluency"`: The translation is not natural or readable in the target
+ *   language.
+ * - `"terminology"`: Incorrect or inconsistent use of domain-specific terms.
+ * - `"style"`: The translation does not match the desired tone or style.
+ */
+type TranslationIssueType = "accuracy" | "fluency" | "terminology" | "style";
+/**
+ * A specific issue found in a translation.
+ */
+interface TranslationIssue {
+  /**
+   * The type of issue.
+   */
+  readonly type: TranslationIssueType;
+  /**
+   * A human-readable description of the issue.
+   */
+  readonly description: string;
+  /**
+   * The location of the issue in the translated text, if applicable.
+   */
+  readonly location?: TranslationIssueLocation;
+}
+/**
+ * The location of a translation issue within the translated text.
+ */
+interface TranslationIssueLocation {
+  /**
+   * The starting character index (0-based, inclusive).
+   */
+  readonly start: number;
+  /**
+   * The ending character index (0-based, exclusive).
+   */
+  readonly end: number;
+}
+/**
+ * Evaluates the quality of a translation using an LLM.
+ *
+ * @param model The language model to use for evaluation.
+ * @param original The original text that was translated.
+ * @param translated The translated text to evaluate.
+ * @param options Evaluation options including target language.
+ * @returns A promise that resolves to the evaluation result.
+ */
+declare function evaluate(model: LanguageModel, original: string, translated: string, options: EvaluateOptions): Promise<EvaluationResult>;
+//#endregion
+export { EvaluateOptions, EvaluationResult, EvaluatorOptions, TranslationEvaluator, TranslationIssue, TranslationIssueLocation, TranslationIssueType, evaluate };