The Trinity Beast — Translation Parameters

Overview

How Parameters Work

-- Aurora: authoritative source
SELECT key, value, description, category, updated_at, updated_by
FROM translation_parameters
ORDER BY category, key;

-- Valkey: fast cache (tx:params hash, 5-min TTL)
HGETALL tx:params

-- Update a parameter (applies immediately to Aurora + Valkey + in-memory)
POST /admin/translate/params
{"key": "pricing.markup_pct", "value": "35", "updated_by": "cory"}

-- Force all containers to reload from Aurora
POST /admin/translate/params/reload

-- View parameters in the TBI Administration dashboard
Translation tab → Translation Parameters section

Fallback Chain

Every parameter accessor follows a three-level fallback to ensure the system never returns zero for a cost value:

1. Valkey tx:params hash — fast path, ~0.1ms, refreshed every 5 minutes
2. Aurora translation_parameters table — authoritative source, ~5ms, used when Valkey is unavailable
3. Hardcoded defaults — safe floor values matching the seed data, used only if both Aurora and Valkey are unreachable

The Cost Formula

The Translation Engine tracks every token at the most granular level Bedrock reports. The ground-truth cost calculation for any translation job is:

cost = (uncached_input_tokens  × input_rate_per_token)
     + (cached_tokens          × cache_read_rate_per_token)   ← 90% cheaper than input
     + (cache_write_tokens     × cache_write_rate_per_token)  ← one-time per cache population
     + (output_tokens          × output_rate_per_token)

Customer Price Formula

What we charge customers is derived from the Bedrock cost plus infrastructure overhead and a service fee markup:

subtotal    = bedrock_cost + infra_per_pair_usd
with_markup = subtotal × (1 + markup_pct / 100)

-- Standard tier (batch, 12-24h SLA):
customer_price = with_markup × (1 - standard_tier_discount_pct / 100)

-- Express tier (real-time, 1-6h SLA):
customer_price = with_markup × (1 + express_tier_premium_pct / 100)

-- Floor:
customer_price = max(customer_price, minimum_quote_usd)

Savings Stack

The three optimization layers compound multiplicatively for internal document translation:

Parameter Categories

subtotal    = bedrock_cost + pricing.infra_per_pair_usd
with_markup = subtotal × (1 + pricing.markup_pct / 100)

Standard tier:  price = with_markup × (1 - pricing.standard_tier_discount_pct / 100)
Express tier:   price = with_markup × (1 + pricing.express_tier_premium_pct / 100)

Final:          price = max(price, pricing.minimum_quote_usd)

Managing Parameters

Via the TBI Administration Dashboard

The easiest way to manage translation parameters is through the TBI Administration dashboard. Navigate to the Translation tab and scroll to the Translation Parameters section (admin only).

• View all parameters: The table shows every parameter with its current Aurora value, live Valkey value, category, last updated date, and who changed it.
• Sync indicator: A green ✓ means Aurora and Valkey are in sync. An amber ⚠ means Valkey has a different value — click Force Reload to resync.
• Edit inline: Click the value field for any row, type the new value, and click Save. The change is written to Aurora and Valkey immediately.
• Add a parameter: Click + Add Param to open the form. Provide a key, value, category, and optional description.
• Force Reload: Flushes the tx:params Valkey cache and reloads from Aurora. All ECS containers pick up changes on their next 5-minute poll cycle.

Via the Admin API

-- List all parameters
GET /admin/translate/params

-- Filter by category
GET /admin/translate/params?category=customer_pricing

-- Update a parameter (applies immediately to Aurora + Valkey + in-memory)
POST /admin/translate/params
{"key": "pricing.markup_pct", "value": "35", "updated_by": "cory"}

-- Force all containers to reload from Aurora
POST /admin/translate/params/reload

Via Aurora SQL (direct)

-- View all parameters
SELECT key, value, category, updated_at, updated_by
FROM translation_parameters
ORDER BY category, key;

-- Update a parameter
UPDATE translation_parameters
SET value = '35', updated_at = NOW(), updated_by = 'cory'
WHERE key = 'pricing.markup_pct';

-- After a direct SQL update, reload Valkey via the API:
POST /admin/translate/params/reload

Nightly Sync Job

The nightly sync job (trinity-beast-sync-job, runs at 1 AM EDT) performs three translation-related tasks:

1. Sync translation_parameters → tx:params

Reads all rows from the translation_parameters Aurora table and writes them to the tx:params Valkey hash with a 5-minute TTL. This ensures all containers have fresh parameter values even if the Valkey cache expired overnight.

2. Rolling 7-day cost averages

Queries translation_job_events for the last 7 days, grouped by model and execution mode. Calculates the average cost-per-chunk for each combination and writes to Valkey:

The 9% infrastructure markup (pricing.infra_markup_pct) is applied to these averages before writing to Valkey. The floor and ceiling from controls.cost_per_chunk_floor and controls.cost_per_chunk_ceiling are also applied.

3. Actual token ratio data

Writes actual token ratios from real jobs to Valkey for operator review:

-- Key pattern: translation:actuals:{model}:{execution_mode}
-- Example: translation:actuals:claude-sonnet-4.6:batch

Fields:
  avg_input_tokens   — average input tokens per pair
  avg_output_tokens  — average output tokens per pair
  avg_cached_tokens  — average cached tokens per pair
  output_input_ratio — derived: avg_output / avg_input
  cache_hit_rate     — derived: avg_cached / avg_input
  pair_count         — number of pairs in the 7-day window
  updated_at         — when this was last calculated

Review these values after each batch run and update estimation.output_input_ratio and estimation.cache_hit_rate in translation_parameters if the actuals drift significantly from the defaults.

Complete Parameter Reference

All 39 parameters in the translation_parameters table, sorted by category and key.