@trazum/core 1.8.0

package/src/i18n/types.ts

@@ -0,0 +1,230 @@
+/**
+ * Internationalisation contract for the core.
+ *
+ * Every user-facing string the core produces lives in a locale catalogue
+ * instead of being hardcoded next to the logic. Adding a locale means adding
+ * one file — it never means touching the rules engine or the pricing model.
+ */
+
+/** Locales shipped with Trazum. English is the source of truth. */
+export const LOCALES = ['en', 'es'] as const;
+
+export type Locale = (typeof LOCALES)[number];
+
+export const DEFAULT_LOCALE: Locale = 'en';
+
+/**
+ * Identifier of every deterministic rule.
+ *
+ * Declared as a union rather than `string` on purpose: adding a rule fails to
+ * compile until every locale catalogue describes it, so a new rule can never
+ * ship with a missing translation.
+ */
+export type RuleId =
+  | 'duplicate-blocks'
+  | 'near-duplicate-blocks'
+  | 'duplicate-lines'
+  | 'verbose-phrases'
+  | 'politeness'
+  | 'filler'
+  | 'hedges'
+  | 'intensifiers'
+  | 'self-check'
+  | 'emphasis'
+  | 'decoration'
+  | 'whitespace';
+
+/** A headline plus its explanation, both already translated. */
+export interface LocalizedMessage {
+  title: string;
+  detail: string;
+}
+
+export interface RuleCopy {
+  title: string;
+  /** What the rule does and why it is safe at its level. */
+  rationale: string;
+}
+
+// --------------------------------------------------------------------------
+// Advisory parameters
+// --------------------------------------------------------------------------
+
+export interface ContextOverflowParams {
+  tokens: number;
+  modelName: string;
+  contextWindow: number;
+}
+
+export interface PromptCachingParams {
+  /** First template placeholder, or `null` when the prompt has none. */
+  placeholder: string | null;
+  prefixTokens: number;
+  totalTokens: number;
+  minTokens: number;
+  modelName: string;
+  /** Cache hit rate as a whole percentage. */
+  hitRatePct: number;
+  /** Cache read price as a percentage of the input price, for this provider. */
+  readPct: number;
+  /** Cache write price as a percentage of the input price, for this provider. */
+  writePct: number;
+  /**
+   * Whether the caller has to mark the prefix.
+   *
+   * Telling somebody on OpenAI to "set cache_control" names a parameter that
+   * does not exist for them: their caching is automatic above a threshold. The
+   * advice to move stable content forward is identical either way — a prefix is
+   * a prefix — but the instruction that follows it is not.
+   */
+  explicit: boolean;
+}
+
+export interface BelowCacheMinimumParams {
+  modelName: string;
+  minTokens: number;
+  placeholder: string | null;
+  prefixTokens: number;
+  totalTokens: number;
+  /** Whether to point at Claude Opus 5's lower 512-token minimum. */
+  mentionLowerMinimum: boolean;
+}
+
+export interface CachePrefixReorderParams {
+  staticTokensAfter: number;
+  sharePct: number;
+  placeholder: string;
+}
+
+export interface ModelDowngradeParams {
+  modelName: string;
+  tier: string;
+  candidateName: string;
+  currentUsd: string;
+  candidateUsd: string;
+}
+
+export interface OutputDominatedParams {
+  outputUsd: string;
+  inputUsd: string;
+}
+
+export interface PromoPricingParams {
+  modelName: string;
+  promoInput: number;
+  promoOutput: number;
+  until: string;
+  listInput: number;
+  listOutput: number;
+}
+
+export interface ContradictoryInstructionsParams {
+  /** Human-readable name of the axis the two instructions disagree on. */
+  axis: string;
+  firstValue: string;
+  firstSnippet: string;
+  secondValue: string;
+  secondSnippet: string;
+  /** How many other axes also disagree, beyond this one. */
+  otherCount: number;
+}
+
+export interface RedundantExamplesParams {
+  redundantCount: number;
+  totalCount: number;
+  redundantTokens: number;
+  /** Similarity of the closest pair, 0-100. */
+  topSimilarityPct: number;
+}
+
+export interface MovableSchemaParams {
+  /** How many cued schema blocks were found. */
+  blocks: number;
+  /** Tokens they hold, fences included. */
+  tokens: number;
+  /** The keys, already formatted for prose. */
+  keyList: string;
+  /** The phrase that identified the block as an output contract. */
+  cue: string;
+}
+
+export interface RestatedOutputFormatParams {
+  restatedCount: number;
+  totalCount: number;
+  restatedTokens: number;
+  /** The restated field names, already formatted for display. */
+  keyList: string;
+}
+
+/** Reasons the optional LLM pass can reject a candidate. */
+export interface LlmMessages {
+  emptyResponse(): string;
+  protectedContentAltered(count: number): string;
+  notShorter(after: number, before: number): string;
+  suspiciousShrink(retainedPct: number): string;
+}
+
+/** Why a proposed rewrite did not survive checking against the prompt. */
+export interface SuggestMessages {
+  'not-found'(): string;
+  'touches-protected'(): string;
+  'introduces-protected'(): string;
+  'no-saving'(): string;
+  overlaps(): string;
+}
+
+/** Everything the core needs to speak one language. */
+export interface CoreMessages {
+  locale: Locale;
+  /** BCP 47 tag used for number formatting (e.g. `en-US`). */
+  numberLocale: string;
+  rules: Record<RuleId, RuleCopy>;
+  llm: LlmMessages;
+  suggest: SuggestMessages;
+  advisories: {
+    contextOverflow(p: ContextOverflowParams): LocalizedMessage;
+    promptCaching(p: PromptCachingParams): LocalizedMessage;
+    promptCachingNotWorthIt(): LocalizedMessage;
+    belowCacheMinimum(p: BelowCacheMinimumParams): LocalizedMessage;
+    cachePrefixReorder(p: CachePrefixReorderParams): LocalizedMessage;
+    batchApi(): LocalizedMessage;
+    modelDowngrade(p: ModelDowngradeParams): LocalizedMessage;
+    outputDominated(p: OutputDominatedParams): LocalizedMessage;
+    promoPricing(p: PromoPricingParams): LocalizedMessage;
+    contradictoryInstructions(p: ContradictoryInstructionsParams): LocalizedMessage;
+    redundantExamples(p: RedundantExamplesParams): LocalizedMessage;
+    restatedOutputFormat(p: RestatedOutputFormatParams): LocalizedMessage;
+    movableSchema(p: MovableSchemaParams): LocalizedMessage;
+  };
+  /** Names of the axes two instructions can disagree on. */
+  contradictionAxes: Record<ContradictionAxisId, string>;
+  /** Names of each end of those axes, as they read inside the advisory. */
+  contradictionValues: Record<ContradictionValueId, string>;
+}
+
+/**
+ * Kept in step with `ContradictionAxis` in `structure.ts`. Declared here so a
+ * new axis fails to compile until every catalogue names it.
+ */
+export type ContradictionAxisId =
+  | 'response-language'
+  | 'output-format'
+  | 'response-length'
+  | 'reasoning-visibility';
+
+/**
+ * The two ends of each axis. Identifiers rather than prose for the same reason
+ * the axes are: the advisory names both sides in its sentence, so leaving them
+ * as English strings in the detector would print English inside a Spanish
+ * report.
+ */
+export type ContradictionValueId =
+  | 'fixed-language'
+  | 'mirror-language'
+  | 'format-json'
+  | 'format-markdown'
+  | 'format-plain-text'
+  | 'length-brief'
+  | 'length-detailed'
+  | 'reasoning-shown'
+  | 'reasoning-hidden';

package/src/index.ts

@@ -0,0 +1,228 @@
+export * from './types.js';
+export { estimateTokens, countTokensAnthropic } from './tokenizer.js';
+export { countSentences, profilePrompt } from './profile.js';
+export { PHRASE_LANGUAGES } from './phrases.js';
+export { toPromptfoo } from './promptfoo.js';
+export { toOtlpMetrics } from './otlp.js';
+export type { OtlpAttribute, OtlpDataPoint, OtlpInput, OtlpMetric, OtlpPayload } from './otlp.js';
+export type { PromptfooExport, PromptfooOptions, PromptfooWarning } from './promptfoo.js';
+export type { ProfileOptions, PromptProfile } from './profile.js';
+export { SUGGEST_SYSTEM_PROMPT, applyRewrites, rejectionText, suggestRewrites } from './suggest.js';
+export type {
+  RejectedReason,
+  RewriteSuggestion,
+  SuggestOptions,
+  SuggestResult,
+} from './suggest.js';
+export type { AsyncTokenCounter, AnthropicCounterOptions } from './tokenizer.js';
+export {
+  MODELS,
+  DEFAULT_MODEL,
+  COST_MULTIPLIERS,
+  PRICING_LAST_REVIEWED,
+  reviewAgeDays,
+  BUNDLED_CATALOGUE,
+  getModel,
+  listModels,
+  effectivePricing,
+  cheapestOfTier,
+  modelFrom,
+  cheapestOfTierIn,
+  multipliersFor,
+} from './pricing.js';
+export type { PricingCatalogue } from './pricing.js';
+export type { CachingMode, Capability, CostMultipliers } from './types.js';
+
+// Local price corrections, so a price change needs no library upgrade.
+export {
+  MAX_PRICING_BYTES,
+  PRICING_MODEL_KEYS,
+  PRICING_OVERLAY_KEYS,
+  PricingOverlayError,
+  applyPricingOverlay,
+  catalogueFromOverlay,
+  parsePricingOverlay,
+} from './pricing-overlay.js';
+export type { PricingOverlay } from './pricing-overlay.js';
+export { openrouterOverlay } from './openrouter.js';
+
+// SigV4 and the Google service-account flow, both hand-rolled on WebCrypto to
+// keep the zero-dependency invariant. Exported so they can be tested directly:
+// a signer that is only reachable through a network call is a signer nothing
+// checks.
+export { amzDates, canonicalRequest, signRequest, signingKey } from './aws-sigv4.js';
+export type { SignInput, SignedHeaders } from './aws-sigv4.js';
+export { accessToken, pkcs8FromPem, signedJwt } from './gcp-auth.js';
+export type { CachedToken, ServiceAccount } from './gcp-auth.js';
+export type { OpenRouterResult } from './openrouter.js';
+export {
+  BASELINE_FILENAME,
+  BASELINE_VERSION,
+  BaselineError,
+  MAX_BASELINE_BYTES,
+  breaches,
+  compareToBaseline,
+  formatBaseline,
+  moneyIsComparable,
+  parseBaseline,
+} from './baseline.js';
+export type {
+  BaselineBreach,
+  BaselineChange,
+  BaselineComparison,
+  BaselineDocument,
+  BaselineThresholds,
+} from './baseline.js';
+export { RULES, getRule } from './rules.js';
+export { segment, join, protectedTexts } from './segment.js';
+export { computeSavings, costOfCall, formatUsd, formatSignedUsd } from './savings.js';
+export { buildAdvisories, recommendTier } from './advisories.js';
+export type { AdvisoryOptions } from './advisories.js';
+export { analyzeCachePrefix } from './cache.js';
+
+// Rearranging a prompt so its stable instructions sit in the cacheable prefix.
+// The largest saving Trazum knows about, and the most dangerous transformation
+// here — see reorder.ts for what it refuses to move and why.
+export { reorderForCache } from './reorder.js';
+export type {
+  DeclinedBlock,
+  ReorderOptions,
+  ReorderResult,
+  ReorderedBlock,
+} from './reorder.js';
+export type { CachePrefixAnalysis } from './cache.js';
+
+// The caching loss that only exists between prompts: a preamble shared by forty
+// files and byte-identical in none of them. Reports no dollar figure on purpose
+// — see shared-prefix.ts for why the cost model cannot price it.
+export { cacheableMinimum, sharedPrefixes } from './shared-prefix.js';
+export type {
+  PrefixCandidate,
+  SharedPrefix,
+  SharedPrefixOptions,
+} from './shared-prefix.js';
+
+// Prompts embedded in source files, found by an explicit marker rather than
+// guessed at — see extract.ts for why a gate cannot afford a heuristic here.
+export { extractPrompts, promptId, hasMarker, SOURCE_EXTENSIONS } from './extract.js';
+export type { ExtractedPrompt, DeclinedPrompt, ExtractionResult } from './extract.js';
+
+// Which provider a prompt is actually sent to, read from the code rather than
+// assumed — see detect.ts for why it declines when a file points two ways.
+export { detectFromSource } from './detect.js';
+export type { Detection, Evidence, EvidenceKind, DetectOptions } from './detect.js';
+export { optimize, withExactTokenCounts, DEFAULT_USAGE } from './optimize.js';
+export {
+  refineWithLlm,
+  openAiCompatible,
+  anthropicProvider,
+  bedrockProvider,
+  geminiProvider,
+  vertexProvider,
+  customProvider,
+  providerFromEnv,
+  REFINER_SYSTEM_PROMPT,
+} from './llm.js';
+export type {
+  RefineOptions,
+  OpenAiCompatibleOptions,
+  AnthropicProviderOptions,
+  BedrockProviderOptions,
+  GeminiProviderOptions,
+  VertexProviderOptions,
+  CustomProviderOptions,
+} from './llm.js';
+
+// Internationalisation
+export {
+  DEFAULT_LOCALE,
+  LOCALES,
+  getMessages,
+  isLocale,
+  matchLocale,
+  resolveLocale,
+  en,
+  es,
+} from './i18n/index.js';
+export type { CoreMessages, Locale, LocalizedMessage, RuleCopy, RuleId } from './i18n/index.js';
+
+// Structural analysis
+export {
+  analyzeExamples,
+  findContradictions,
+  findExamples,
+  findMovableSchema,
+  findRestatedFormat,
+} from './structure.js';
+export type {
+  Contradiction,
+  ContradictionAxis,
+  ContradictionSide,
+  ExampleAnalysis,
+  ExampleBlock,
+  MovableSchema,
+  RedundantExample,
+  RestatedFormat,
+} from './structure.js';
+export { jaccard, normalizeForCompare } from './similarity.js';
+export { OUTPUT_CUES, OUTPUT_CUES_BY_LANGUAGE } from './phrases.js';
+
+// Endpoint validation for the pluggable LLM layer
+export {
+  SAFE_FETCH_INIT,
+  allowedEndpoints,
+  checkedEndpoint,
+  isPrivateHost,
+  resolveEndpoint,
+  validateLlmEndpoint,
+} from './net.js';
+export type { EndpointRejection, ValidateEndpointOptions } from './net.js';
+
+// Per-rule change extraction
+export { extractChanges, DEFAULT_CHANGE_LIMIT } from './changes.js';
+export type { RuleChange } from './changes.js';
+
+// Semantic review of few-shot examples (optional, costs an LLM call)
+export { reviewExamples, EXAMPLE_REVIEW_SYSTEM_PROMPT } from './review.js';
+export type { ExampleReview, ExampleRedundancy, ReviewExamplesOptions } from './review.js';
+
+// Which few-shot examples earn their tokens, measured by leave-one-out. Optional,
+// and the most expensive thing here: see prune.ts for the call arithmetic and for
+// what the measurement cannot tell you.
+export { NothingToPrune, plannedCalls, pruneExamples, withoutExample } from './prune.js';
+export type { ExampleContribution, PruneOptions, PruneReport } from './prune.js';
+
+// Golden-set evaluation (optional, costs three LLM calls per case)
+export { evaluate, fillPrompt, verdictFor } from './evaluate.js';
+export type { EvalCase, EvalReport, EvalVerdict, EvaluateOptions } from './evaluate.js';
+
+// Comparing two prompt versions
+export { comparePrompts } from './compare.js';
+export type {
+  PromptComparison,
+  CompareOptions,
+  RuleDelta,
+  AdvisoryDelta,
+} from './compare.js';
+
+// Glob matching for config budget patterns. Pure, so it belongs here; the
+// config loader and directory walk that use it read the filesystem and live in
+// "@trazum/core/node" instead — see node.ts for why that split is structural.
+export { matchGlob, mostSpecificMatch, specificity } from './glob.js';
+export { editDistance, nearestName } from './nearest.js';
+
+// The config *schema*, without the loader: validation is a pure function of a
+// string, so it belongs on the browser-safe entry point. `loadConfig`, which
+// actually opens the file, is only in "@trazum/core/node".
+export {
+  CONFIG_FILENAME,
+  CONFIG_KEYS,
+  CONFIG_USAGE_KEYS,
+  ConfigError,
+  DEFAULT_EXTENSIONS,
+  MAX_CONFIG_BYTES,
+  MAX_CONFIG_SEARCH_DEPTH,
+  budgetFor,
+  parseConfig,
+} from './config-schema.js';
+export type { ResolvedBudget, TrazumConfig } from './config-schema.js';