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, 27-hour TTL)
HGETALL tx:params

-- Update a parameter (applies immediately to Aurora + Valkey + in-memory)
POST /admin/translate/params
{"key": "pricing.markup_pct", "value": "30", "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 nightly by sync job (27-hour TTL)
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

Here is the thing to understand before you read a single line of the formula below: customers pay a true flat 3.00 USD per document-language pair. For every model except Claude Opus 4.8, the cost-plus calculation below no longer runs at all — the flat 3.00 USD rate is applied directly, per pair. The formula survives for exactly one agent: Claude Opus 4.8, where cost-plus runs with 3.00 USD as a floor, so a large Opus document can price above it and is advertised as "From 3.00". So the formula is real, but only Opus ever exercises it; everything else is a flat rate.

That is a deliberate design choice worth appreciating rather than a rounding convenience. A cost-plus price on a small document produces a quote of a few cents, and a few cents cannot carry a Stripe fee, a confirmation email, and a support conversation. Pricing on the floor gives the customer something far more valuable than precision: a number they can predict before they ask. Nine documents into three languages is 27 pairs, so 81.00 USD, and they can work that out themselves without a quote call.

infra       = InfraCostForJob(translatable_bytes_per_doc, num_languages)
subtotal    = total_bedrock_cost + infra
service_fee = subtotal × (pricing.markup_pct / 100)
total       = subtotal + service_fee

total_pairs = doc_count × language_count
pair_floor  = pricing.minimum_per_pair_usd × total_pairs

final       = max(total, pair_floor, pricing.minimum_quote_usd)

That formula now executes on a single path — Claude Opus 4.8 — and its last line is where the money is decided there: three candidates compete and the largest wins, so the cost-based total takes the price only when it beats the 3.00 USD per-pair floor. Opus 4.8 bills 5.50 USD per million input tokens and 27.50 USD per million output tokens, the highest rates in the table and about 1.7 times Sonnet 4.6, so it is the one model whose token bill can climb past the floor, on documents above about 200 KB. For every other agent there is no competition to resolve: the price is 3.00 USD per pair, full stop.

Two floors exist rather than one, and the distinction matters when you are reading a quote. pricing.minimum_per_pair_usd scales with the work — it is 3.00 USD multiplied by the pair count. pricing.minimum_quote_usd is an absolute backstop on the whole quote, also 3.00 USD, which catches the smallest possible job of one document into one language. On any job larger than a single pair, the per-pair floor is the one doing the work.

Savings Stack

Two optimization layers compound for internal document translation, and both act on the cost side rather than the price side — they widen the margin under the floor rather than changing what a customer pays:

Parameter Categories

infra       = InfraCostForJob(translatable_bytes_per_doc, num_languages)
subtotal    = total_bedrock_cost + infra
service_fee = subtotal × (pricing.markup_pct / 100)
total       = subtotal + service_fee

total_pairs = doc_count × language_count
pair_floor  = pricing.minimum_per_pair_usd × total_pairs

final       = max(total, pair_floor, pricing.minimum_quote_usd)   ← Opus path only

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": "30", "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, BeastReconciler, runs at 1 AM EDT) performs four translation-related tasks, and the first one is new in October 2026:

0. Refresh Bedrock rates from the AWS Price List

Before anything is copied, the job asks AWS what each model costs today. It calls the public Price List (pricing:GetProducts, served from us-east-1 and filtered to us-east-2, where our Bedrock traffic runs) for all seven rate keys, checks every value, and writes any change into the bedrock_pricing rows of Aurora. Step 1 then carries the fresh rates into tx:params in the same run, and a final check confirms Valkey holds exactly what Aurora holds.

It is careful in the way a price source has to be. Each model is all-or-nothing: a fetch error, a missing dimension, an unknown unit, a value outside 0.0001–500 USD per million tokens, or a change of more than 3× in one night keeps that model's stored rates and adds one line to a single ops alert. Nothing in it can stop the rest of the nightly job. For a deploy, SYNC_ONLY=bedrock-rates runs only the refresh, the copy and the check, so the day's spend and token guards are never reset mid-day.

flowchart LR
    subgraph AWS["AWS Price List (us-east-1 endpoint)"]
        PL["GetProducts
us-east-2 rates, 7 models"]
    end
    subgraph SYNC["Sync job (BeastReconciler, 1 AM nightly)"]
        CHK{"Every value plausible?
unit known, 0.0001-500,
no jump over 3x"}
        KEEP["Keep stored rates
for that model"]
        ALERT["One ops alert
for the whole run"]
        VER{"Aurora = tx:params?"}
    end
    subgraph DATA["Stores"]
        AUR[("Aurora
translation_parameters
bedrock_pricing rows")]
        VK[("Valkey
tx:params, 27 h TTL")]
    end
    LPO["LPO containers
quote and cost math"]
    PL --> CHK
    CHK -->|"yes: write changes"| AUR
    CHK -->|"no"| KEEP
    KEEP --> ALERT
    AUR -->|"Step 1 copies the table"| VK
    VK --> VER
    VER -->|"no"| ALERT
    VK -->|"read first"| LPO
    AUR -.->|"fallback"| LPO
    style AWS fill:#3b2a5c,stroke:#a78bfa,color:#ffffff
    style SYNC fill:#1e3a5f,stroke:#60a5fa,color:#ffffff
    style DATA fill:#14403a,stroke:#10b981,color:#ffffff
    style PL fill:#2e1065,stroke:#a78bfa,color:#e2e8f0
    style CHK fill:#422006,stroke:#fbbf24,color:#e2e8f0
    style KEEP fill:#422006,stroke:#fbbf24,color:#e2e8f0
    style ALERT fill:#7f1d1d,stroke:#fca5a5,color:#e2e8f0
    style VER fill:#422006,stroke:#fbbf24,color:#e2e8f0
    style AUR fill:#064e3b,stroke:#10b981,color:#e2e8f0
    style VK fill:#064e3b,stroke:#10b981,color:#e2e8f0
    style LPO fill:#334155,stroke:#94a3b8,color:#e2e8f0
    linkStyle 0,1,4 stroke:#10b981,stroke-width:2px
    linkStyle 2,3,6 stroke:#fbbf24,stroke-width:2px
    linkStyle 5 stroke:#60a5fa,stroke-width:2px
    linkStyle 7,8 stroke:#94a3b8,stroke-width:2px
        

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 27-hour TTL, so the hash always outlives the next run. This ensures all containers have fresh parameter values, including the rates refreshed in step 0, 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 floor and ceiling from controls.cost_per_chunk_floor and controls.cost_per_chunk_ceiling are applied to these averages before they are written to Valkey. Note that the batch and batch_cached variants above are historical: batch inference was removed on June 20, 2026, so those keys are retained for backward compatibility and are no longer written with fresh data. There is also no longer an infrastructure markup applied at this stage — pricing.infra_markup_pct existed to mark up the batch pipeline's averages and went away with it.

3. Actual token ratio data

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

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

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 periodically and update estimation.output_input_ratio and estimation.cache_hit_rate in translation_parameters when the actuals have drifted from the stored defaults. This is the feedback loop that keeps every future quote grounded in what the engine really did rather than in what it was once assumed to do.

Complete Parameter Reference

The 46 parameters read from the live translation_parameters table on 2026-10-10, plus the six refund rows and the controls.max_docs_per_request update of the October 2026 migration, and the rate rows the nightly refresh adds for the new Claude agents, sorted by category and key. Read the live table with GET /admin/translate/params for today's exact values and count.