# Fix the glossary lookup agent timing out mid batch

## TL;DR

Glossary lookups block the batch, so cache lookups and parallelize with a concurrency cap. Each uncached lookup is a network round trip, and thousands of them serialize into a timeout. Cache term results in memory, batch the misses, and the batch finishes with consistent terms.

## The error

```text
Glossary lookup agent: timeout mid batch, 800 of 2000 terms looked up
later strings used different terms than earlier ones
```

## Fix it

### Step 1: Confirm lookups are the bottleneck

```bash
grep -n "glossary lookup" logs/batch.log | head -3
```

Expected: You see per-term network calls dominating time.

### Step 2: Add an in-memory term cache

```bash
node -e "console.log('pattern: Map of term to result, check before every API call')"
```

Expected: Repeat terms cost nothing.

### Step 3: Parallelize with a small concurrency cap

```bash
node -e "console.log('run 4 to 8 lookups in flight, no more -- politeness plus speed')"
```

Expected: Throughput rises without tripping limits.

### Step 4: Rerun the batch and check term consistency

```bash
node scripts/batch-translate.js | tail -3
```

Expected: All 2000 terms resolve and identical source terms map to identical translations.

## When to use this

- Glossary lookups time out mid batch
- Term usage is inconsistent across the batch

## When NOT to use this

- The glossary has no entry for the term, add it
- Lookups are fast but wrong, check the glossary content

## Tool and version compatibility

- TMS glossary APIs, batch translation agents
- In-memory caching, bounded concurrency

## Variant phrasings

### timeout only on first run

Cold cache. Warm it from the previous batch's cache file.

### glossary API rate limits instead

Same caching fix, plus backoff. The cache is what saves you from the limit.

## Why it happens

Each lookup is a network call, and naive agents do them serially per string. Repeated terms each pay the full cost, the batch slows to a crawl, and the timeout fires mid-way, leaving later strings translated without glossary guidance.

## Edge cases

- Persist the cache between runs, glossaries change slowly
- Invalidate on glossary version change, stale terms are worse than slow ones
- Log cache hit rate, a low rate means the batching is wrong

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CqCtGmt_hauXNpzIVzNcSg