The Math · JavaScript · Python · npm · Vostride AI

id-agent

Token efficient IDs for AI agents.

AI agents pass IDs through prompts, tool calls, logs, traces, and memory. UUIDs are great for databases, but they are expensive in context windows and hard for humans or LLMs to copy reliably. id-agent gives you word-based IDs that are compact in modern tokenizers, readable in logs, and configurable by collision budget.

Where UUIDs cost about 23 tokens and get hallucinated by LLMs, id-agent produces memorable word-based IDs at about 14 tokens with strong collision resistance. It is built for the context window, not just the database.

• Human-readable -- word-based IDs that humans and LLMs can remember.
• Token-efficient -- every word in the wordlist is exactly 1 BPE token on o200k_base.
• Collision-safe -- configurable entropy from about 12 to 192 bits.
• Validated inputs -- descriptive validation on all public APIs.

The Math

Token Cost Comparison

id-agent - 8 words, 43 chars, 12 tokens

UUID v4 - 36 chars, 26 tokens

Entropy

Each word is drawn uniformly from a curated 4096-word list (2^12). Every position in the ID is an independent random selection:

Entropy per word = log2(4096) = 12 bits
Total entropy    = words * 12 bits
ID space         = 4096^words = 2^(words * 12)

This holds regardless of individual word length. A 3-character word and a 6-character word both contribute exactly 12 bits because the attacker must guess from the same 4096-word pool.

Collision Probability

The probability of at least one collision among n randomly generated IDs:

P(collision) ~= n^2 / (2 * 2^b)

where b = total bits of entropy

This is the birthday paradox approximation, valid when P is small (P < 0.01).

The default 8-word ID is safe for more than 300 trillion items before reaching a 50% collision chance. Most applications will never generate more than a few million IDs.

Worked Example

For the default 8-word ID at 1 million items:

b = 8 * 12 = 96 bits
n = 1,000,000

P ~= (10^6)^2 / (2 * 2^96)
  = 10^12 / (2 * 7.92 * 10^28)
  = 10^12 / (1.58 * 10^29)
  = 6.3 * 10^-18

That is roughly 1 in 158 quadrillion.

Token Cost

All measurements use o200k_base (GPT-4o, GPT-4.1, o1, o3) through tiktoken. Token counts vary slightly per ID because of BPE merge behavior with hyphens. Values below are averages over 100 samples:

Choosing Word Count

The right word count depends on your scale. The default of 8 is deliberately conservative and globally safe.

Why Words Beat Hex

BPE tokenizers used by modern LLMs were trained on natural language. Short English words are single tokens by design. UUIDs are hex strings that split unpredictably:

"storm-delta-stone"  =>  4 tokens (3 words + separators)
"dc193952-186a-4645" =>  11 tokens (same 18 characters)

id-agent's wordlist is curated so every word is exactly 1 BPE token on o200k_base. The hyphens add about 1 token per 6 words due to BPE merge behavior. This is why word-based IDs are fundamentally more token-efficient than random hex or alphanumeric strings.

Implementations

id-agent is implemented as first-class packages for:

• JavaScript / TypeScript
• Python

Both implementations use the same 4096-word list, separator rules, entropy model, prefix validation, and public behavior.

How It Works

id-agent uses a curated wordlist of 4096 English words, each verified as a single BPE token on the o200k_base tokenizer used by GPT-4o and GPT-4.1. Words are 3-6 characters and filtered for offensive terms and homophones.

Random IDs use cryptographically secure randomness. Deterministic IDs use HMAC-SHA256, mapping hash bytes to wordlist indices.

JavaScript / TypeScript

Install

npm install id-agent

pnpm add id-agent

Quick Start

import { idAgent } from 'id-agent'

const id = idAgent()
// => "urd-antes-sorry-pac-dire-total-expire-going"

const taskId = idAgent({ prefix: 'task' })
// => "task_slide-exact-cede-bury-linge-ease-bean-impact"

const short = idAgent({ words: 3 })
// => "front-reject-tho"

Random IDs

Generate a random, human-readable ID.

import { idAgent } from 'id-agent'

idAgent()                         // 8 words, about 96 bits
idAgent({ words: 5 })             // 5 words, about 60 bits
idAgent({ prefix: 'user' })       // "user_cloud-train-scope-frame-match-level-paint-field"

Options:

Deterministic IDs

Generate a deterministic ID from a string input using HMAC-SHA256. The same input always produces the same ID.

import { idAgent } from 'id-agent'

const id = await idAgent.from('[email protected]')

const namespaced = await idAgent.from('[email protected]', {
  namespace: 'my-app',
  prefix: 'user',
  words: 5,
})

Options:

Parse

Parse any id-agent ID into its components. Supports hyphen-separated and underscore-separated words. Returns null for unrecognized formats.

import { parse } from 'id-agent'

parse('task_storm-delta-stone')
// => { prefix: 'task', words: ['storm', 'delta', 'stone'], wordCount: 3, bits: 36, raw: 'task_storm-delta-stone', format: 'readable' }

parse('task_storm_delta_stone')
// => { prefix: 'task', words: ['storm', 'delta', 'stone'], wordCount: 3, bits: 36, raw: 'task_storm_delta_stone', format: 'readable' }

Validate

Check if a string is a valid id-agent ID. Validation confirms that all words exist in the WORDLIST.

import { validate } from 'id-agent'

validate('storm-delta-stone')
// => { valid: true, prefix: undefined, wordCount: 3 }

validate('task_jump-notaword')
// => { valid: false, reason: 'unknown words: notaword' }

validate('INVALID')
// => { valid: false, reason: 'contains uppercase characters' }

Alias Maps

Create a bidirectional alias map for token reduction in LLM contexts. Maps long IDs to short word-based aliases with replace and restore support.

import { createAliasMap } from 'id-agent'

const aliases = createAliasMap({ words: 3 })
aliases.set('8cdda07b-85d2-459c-8a2a-83c8f9245dbe')
// => "storm-delta-stone"

aliases.get('storm-delta-stone')
// => "8cdda07b-85d2-459c-8a2a-83c8f9245dbe"

const text = 'Process 8cdda07b-85d2-459c-8a2a-83c8f9245dbe then 6ba7b810-9dad-11d1-80b4-00c04fd430c8'
const shortened = aliases.replace(text, {
  pattern: /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi,
})
// => "Process storm-delta-stone then cloud-train-scope"

const restored = aliases.restore(shortened)
// => original text

aliases.entries()
// => [["8cdda07b-85d2-459c-8a2a-83c8f9245dbe", "storm-delta-stone"], ...]

Options:

Duplicate Detection

Scan text for duplicate IDs using a regex pattern. This is a pure function with no filesystem access.

import { detectDuplicates } from 'id-agent'

const dupes = detectDuplicates({
  pattern: /[a-z]+(?:-[a-z]+)+/,
  text: 'Found storm-delta-stone in file A and storm-delta-stone in file B',
})
// => [{ id: 'storm-delta-stone', count: 2 }]

const dupes2 = detectDuplicates({
  pattern: /task_[a-z]+(?:-[a-z]+)+/,
  text: ['const x = "task_red-fox-run"', 'const y = "task_red-fox-run"'],
})

Options:

WORDLIST

Direct access to the curated 4096-word list. Every word is exactly 1 BPE token on o200k_base. The JavaScript export is a frozen array.

import { WORDLIST } from 'id-agent'

WORDLIST.length           // => 4096
Object.isFrozen(WORDLIST) // => true

Python

Install

pip install id-agent

uv add id-agent

Quick Start

from id_agent import generate

id = generate()
# => "urd-antes-sorry-pac-dire-total-expire-going"

task_id = generate(prefix="task")
# => "task_slide-exact-cede-bury-linge-ease-bean-impact"

short = generate(words=3)
# => "front-reject-tho"

Random IDs

Generate a random, human-readable ID.

from id_agent import generate

generate()                      # 8 words, about 96 bits
generate(words=5)               # 5 words, about 60 bits
generate(prefix="user")         # "user_cloud-train-scope-frame-match-level-paint-field"

Options:

Deterministic IDs

Generate a deterministic ID from a string input using HMAC-SHA256. The same input always produces the same ID.

from id_agent import generate_deterministic

id = generate_deterministic("[email protected]")

namespaced = generate_deterministic(
    "[email protected]",
    namespace="my-app",
    prefix="user",
    words=5,
)

Options:

Parse

Parse any id-agent ID into its components. Supports hyphen-separated and underscore-separated words. Returns None for unrecognized formats.

from id_agent import parse

parse("task_storm-delta-stone")
# => ParsedId(prefix="task", words=("storm", "delta", "stone"), word_count=3, bits=36.0, raw="task_storm-delta-stone", format="readable")

parse("task_storm_delta_stone")
# => ParsedId(prefix="task", words=("storm", "delta", "stone"), word_count=3, bits=36.0, raw="task_storm_delta_stone", format="readable")

Validate

Check if a string is a valid id-agent ID. Validation confirms that all words exist in the WORDLIST.

from id_agent import validate

validate("storm-delta-stone")
# => ValidationResult(valid=True, prefix=None, word_count=3, words=("storm", "delta", "stone"))

validate("task_jump-notaword")
# => ValidationResult(valid=False, reason="unknown words: notaword", unknown_words=("notaword",))

validate("INVALID")
# => ValidationResult(valid=False, reason="contains uppercase characters")

Alias Maps

Create a bidirectional alias map for token reduction in LLM contexts. Maps long IDs to short word-based aliases with replace and restore support.

from id_agent import AliasMap

aliases = AliasMap(words=3)
aliases.set("8cdda07b-85d2-459c-8a2a-83c8f9245dbe")
# => "storm-delta-stone"

aliases.get("storm-delta-stone")
# => "8cdda07b-85d2-459c-8a2a-83c8f9245dbe"

text = "Process 8cdda07b-85d2-459c-8a2a-83c8f9245dbe then 6ba7b810-9dad-11d1-80b4-00c04fd430c8"
shortened = aliases.replace(
    text,
    pattern=r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
)
# => "Process storm-delta-stone then cloud-train-scope"

restored = aliases.restore(shortened)
# => original text

aliases.entries()
# => (("8cdda07b-85d2-459c-8a2a-83c8f9245dbe", "storm-delta-stone"), ...)

Options:

Duplicate Detection

Scan text for duplicate IDs using a regex pattern. This is a pure function with no filesystem access.

from id_agent import detect_duplicates

dupes = detect_duplicates(
    pattern=r"[a-z]+(?:-[a-z]+)+",
    text="Found storm-delta-stone in file A and storm-delta-stone in file B",
)
# => [DuplicateResult(id="storm-delta-stone", count=2)]

dupes2 = detect_duplicates(
    pattern=r"task_[a-z]+(?:-[a-z]+)+",
    text=['const x = "task_red-fox-run"', 'const y = "task_red-fox-run"'],
)

Options:

WORDLIST

Direct access to the curated 4096-word list. Every word is exactly 1 BPE token on o200k_base. The Python export is an immutable tuple.

from id_agent import WORDLIST

len(WORDLIST)                 # => 4096
isinstance(WORDLIST, tuple)   # => True

License

MIT