id-agent 1.1.3__py3-none-any.whl

id_agent/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ._alias import AliasMap
+from ._detect import detect_duplicates
+from ._generate import generate, generate_deterministic
+from ._parse import parse, validate
+from ._types import DuplicateResult, ParsedId, ValidationResult
+from ._wordlist import WORDLIST
+
+__all__ = [
+    "generate",
+    "generate_deterministic",
+    "parse",
+    "validate",
+    "AliasMap",
+    "detect_duplicates",
+    "WORDLIST",
+    "ParsedId",
+    "ValidationResult",
+    "DuplicateResult",
+]

id_agent/_alias.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import re
+
+from ._generate import _validate_words, generate
+
+
+class AliasMap:
+    def __init__(self, words: int, allow_collision: bool = False) -> None:
+        self._words = _validate_words(words)
+        if not isinstance(allow_collision, bool):
+            raise TypeError("allow_collision must be a bool")
+        self._allow_collision = allow_collision
+        self._forward: dict[str, str] = {}
+        self._reverse: dict[str, str] = {}
+
+    def set(self, original: str) -> str:
+        if not isinstance(original, str):
+            raise TypeError("original must be a string")
+
+        existing = self._forward.get(original)
+        if existing is not None:
+            return existing
+
+        while True:
+            alias = generate(words=self._words)
+            if self._allow_collision or alias not in self._reverse:
+                break
+
+        self._forward[original] = alias
+        self._reverse[alias] = original
+        return alias
+
+    def get(self, alias: str) -> str | None:
+        if not isinstance(alias, str):
+            raise TypeError("alias must be a string")
+        return self._reverse.get(alias)
+
+    def clear(self) -> None:
+        self._forward.clear()
+        self._reverse.clear()
+
+    def __len__(self) -> int:
+        return len(self._forward)
+
+    def entries(self) -> tuple[tuple[str, str], ...]:
+        return tuple(self._forward.items())
+
+    def replace(self, text: str, pattern: str | re.Pattern[str] | None = None) -> str:
+        if not isinstance(text, str):
+            raise TypeError("text must be a string")
+
+        if pattern is not None:
+            compiled = _compile_pattern(pattern)
+            matches = dict.fromkeys(match.group(0) for match in compiled.finditer(text))
+            for match in matches:
+                self.set(match)
+
+        regex = _build_replacement_regex(self._forward.keys())
+        if regex is None:
+            return text
+        return regex.sub(lambda match: self._forward.get(match.group(0), match.group(0)), text)
+
+    def restore(self, text: str) -> str:
+        if not isinstance(text, str):
+            raise TypeError("text must be a string")
+
+        regex = _build_replacement_regex(self._reverse.keys())
+        if regex is None:
+            return text
+        return regex.sub(lambda match: self._reverse.get(match.group(0), match.group(0)), text)
+
+
+def _compile_pattern(pattern: str | re.Pattern[str]) -> re.Pattern[str]:
+    if isinstance(pattern, str):
+        return re.compile(pattern)
+    if isinstance(pattern, re.Pattern):
+        return pattern
+    raise TypeError("pattern must be a string regex, compiled regex, or None")
+
+
+def _build_replacement_regex(keys: object) -> re.Pattern[str] | None:
+    sorted_keys = sorted((str(key) for key in keys), key=len, reverse=True)
+    if not sorted_keys:
+        return None
+    return re.compile("|".join(re.escape(key) for key in sorted_keys))

id_agent/_detect.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ._types import DuplicateResult
+
+
+def detect_duplicates(
+    text: str | Iterable[str],
+    pattern: str | re.Pattern[str],
+) -> list[DuplicateResult]:
+    texts = _normalize_texts(text)
+    compiled = _compile_pattern(pattern)
+    counts: dict[str, int] = {}
+
+    for item in texts:
+        for match in compiled.finditer(item):
+            matched_id = match.group(0)
+            counts[matched_id] = counts.get(matched_id, 0) + 1
+
+    return [
+        DuplicateResult(id=matched_id, count=count)
+        for matched_id, count in counts.items()
+        if count > 1
+    ]
+
+
+def _normalize_texts(text: str | Iterable[str]) -> tuple[str, ...]:
+    if isinstance(text, str):
+        return (text,)
+    if not isinstance(text, Iterable):
+        raise TypeError("text must be a string or iterable of strings")
+
+    texts = tuple(text)
+    if not all(isinstance(item, str) for item in texts):
+        raise TypeError("text iterable must contain only strings")
+    return texts
+
+
+def _compile_pattern(pattern: str | re.Pattern[str]) -> re.Pattern[str]:
+    if isinstance(pattern, str):
+        return re.compile(pattern)
+    if isinstance(pattern, re.Pattern):
+        if not isinstance(pattern.pattern, str):
+            raise TypeError("pattern must match strings")
+        return pattern
+    raise TypeError("pattern must be a string regex or compiled regex")

id_agent/_generate.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import secrets
+
+from ._wordlist import WORDLIST
+
+_MIN_WORDS = 1
+_MAX_WORDS = 16
+_DEFAULT_WORDS = 8
+_DEFAULT_NAMESPACE = "id-agent"
+_PREFIX_RE = re.compile(r"^[a-z0-9]+$")
+
+
+def _validate_words(words: int) -> int:
+    if not isinstance(words, int) or isinstance(words, bool):
+        raise TypeError("words must be an integer")
+    if words < _MIN_WORDS:
+        raise ValueError("words must be at least 1")
+    if words > _MAX_WORDS:
+        raise ValueError("words must be at most 16")
+    return words
+
+
+def _validate_prefix(prefix: str | None) -> str | None:
+    if prefix is None:
+        return None
+    if not isinstance(prefix, str):
+        raise TypeError("prefix must be a string or None")
+    if not _PREFIX_RE.fullmatch(prefix):
+        raise ValueError("prefix must be lowercase alphanumeric")
+    return prefix
+
+
+def _format_id(prefix: str | None, body: str) -> str:
+    return f"{prefix}_{body}" if prefix else body
+
+
+def generate(*, words: int = _DEFAULT_WORDS, prefix: str | None = None) -> str:
+    word_count = _validate_words(words)
+    checked_prefix = _validate_prefix(prefix)
+    selected = [secrets.choice(WORDLIST) for _ in range(word_count)]
+    return _format_id(checked_prefix, "-".join(selected))
+
+
+def generate_deterministic(
+    input: str,
+    *,
+    namespace: str | None = None,
+    words: int = _DEFAULT_WORDS,
+    prefix: str | None = None,
+) -> str:
+    if not isinstance(input, str):
+        raise TypeError("input must be a non-empty string")
+    if input == "":
+        raise ValueError("input must be a non-empty string")
+    if namespace is None:
+        checked_namespace = _DEFAULT_NAMESPACE
+    elif not isinstance(namespace, str):
+        raise TypeError("namespace must be a string or None")
+    elif namespace == "":
+        raise ValueError("zero-length namespace is not supported")
+    else:
+        checked_namespace = namespace
+
+    word_count = _validate_words(words)
+    checked_prefix = _validate_prefix(prefix)
+    digest = hmac.new(
+        checked_namespace.encode("utf-8"),
+        input.encode("utf-8"),
+        hashlib.sha256,
+    ).digest()
+    selected = [
+        WORDLIST[int.from_bytes(digest[i * 2 : i * 2 + 2], "big") % len(WORDLIST)]
+        for i in range(word_count)
+    ]
+    return _format_id(checked_prefix, "-".join(selected))

id_agent/_parse.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import math
+import re
+
+from ._types import ParsedId, ValidationResult
+from ._wordlist import WORDLIST
+
+_READABLE_BODY_RE = re.compile(r"^[a-z]{2,}(?:[-_][a-z]{2,})*$")
+_WORD_SEPARATOR_RE = re.compile(r"[-_]")
+_BITS_PER_WORD = math.log2(len(WORDLIST))
+_WORD_SET = frozenset(WORDLIST)
+
+
+def parse(id: object) -> ParsedId | None:
+    if not isinstance(id, str) or id == "":
+        return None
+
+    prefix: str | None = None
+    body = id
+
+    underscore_index = id.find("_")
+    if underscore_index > 0:
+        prefix = id[:underscore_index]
+        body = id[underscore_index + 1 :]
+
+    if body == "":
+        return None
+
+    if not _READABLE_BODY_RE.fullmatch(body):
+        return None
+
+    words = tuple(_WORD_SEPARATOR_RE.split(body))
+    return ParsedId(
+        prefix=prefix,
+        words=words,
+        word_count=len(words),
+        bits=len(words) * _BITS_PER_WORD,
+        raw=id,
+        format="readable",
+    )
+
+
+def validate(id: object) -> ValidationResult:
+    if not isinstance(id, str) or id == "":
+        return ValidationResult(valid=False, reason="empty string")
+    if re.search(r"[A-Z]", id):
+        return ValidationResult(valid=False, reason="contains uppercase characters")
+    if re.search(r"[^a-z0-9_-]", id):
+        return ValidationResult(valid=False, reason="contains invalid characters")
+
+    parsed = parse(id)
+    if parsed is None:
+        return ValidationResult(valid=False, reason="unrecognized format")
+
+    unknown_words = tuple(word for word in parsed.words if word not in _WORD_SET)
+    if unknown_words:
+        return ValidationResult(
+            valid=False,
+            reason=f"unknown words: {', '.join(unknown_words)}",
+            unknown_words=unknown_words,
+        )
+
+    return ValidationResult(
+        valid=True,
+        prefix=parsed.prefix,
+        word_count=parsed.word_count,
+        words=parsed.words,
+    )

id_agent/_types.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class ParsedId:
+    prefix: str | None
+    words: tuple[str, ...]
+    word_count: int
+    bits: float
+    raw: str
+    format: Literal["readable"]
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    valid: bool
+    reason: str | None = None
+    prefix: str | None = None
+    word_count: int | None = None
+    words: tuple[str, ...] = ()
+    unknown_words: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class DuplicateResult:
+    id: str
+    count: int

id_agent/_wordlist.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+WORDLIST: tuple[str, ...] = tuple(
+    (
+        "aal aani aba abama abas abase abb abba abby abe abel abele abet abidi abies able abler "
+        "ably abort about abouts above abox abu abut aby acca accent accept access accord ace "
+        "acer aces ach achar ache achen acher aching acid acier acker acle acor acre act acting "
+        "action active actor acts actual acute ada adai adam adapt adar adat aday adays add "
+        "adda added adder addle adds addy ade adet adin adjust admin ado adult advert ady adz "
+        "aes afar affa affirm aft after aga again agal agama agar agate age aged agen agena "
+        "agency agenda agent ager ages agger aghan aging agio agnes ago agog agon agonal agra "
+        "agre agree agua ague agy aha ahead ahir aho ahu aias aid ail ailing ails aim aint air "
+        "aira aire airs airt airy ait ajar ajari aka akal akala akan ake akey akia akin akka "
+        "ako akov aku ala alada alaki alala alan aland alar alarm alary alas alb album ale alea "
+        "alee alem alen alert ales alette alex alf alias alice alida alien align alin aline "
+        "alist alit alite alive alk all allah allan alle allen aller allow ally alma almost alo "
+        "alogy alone along alp alpha also alt altar alter altern alto alur always aly alya ama "
+        "amah amain amang amani amar amara amarin amazon amba ambar amber amble ambo ame amen "
+        "ament ami amia amic amid amide amil amin amine amini amir amma amman ammer ammo ammu "
+        "among amor amos amount amp ample amt amy ana anam anan anana anas anat anay anchor and "
+        "anda ande andi andre andy anele anes angel angelo anger angers angka angle angled "
+        "angler angles ango ani animal anime anion anis anker ann anna anne annet annie annual "
+        "anoa anon ansa anser ansu answer ant anta antal antar antara ante antes anthem anti "
+        "antic anton ants antu any apa apache apar apart apatan ape aper aping apis apollo "
+        "aport appear append apple apply apps apse apt apus ara arab arad arar arc arca arch "
+        "arched arches archie archy ardu are area ared arena argas argent argo argon aria arian "
+        "aries ariot arius ark arks arm armed arming armor arms army arn arna arne arni aro "
+        "around arrant arras array arris arrow arry art artar artha artist arts arty aru arum "
+        "ary aryl asa asana ascii ascus ase asem ash asha ashen asher ashes ashy asian aside "
+        "ask askar asks asp aspect asper assert asset assets assi assign assis assist ast asta "
+        "aster astern astian ata atap ate aten ates athing ati atik atis atlas atma atom atomic "
+        "atoms atria atta attach attack attar atter attern attery audio audit auge augh aught "
+        "auh auk aum aus author auto autos ava avail aval avar ave avens aver avera averse "
+        "avery aves avian avid avis avo avoid awa await awake awan award aware awat away awd "
+        "awin awl awn awner awning axe axed axes axis axon ayah aye ayin ayu azine azo azole "
+        "azon azure baa baar bab babel baby bac bach back backs backup bad badge bae bag bags "
+        "bah bait baka bal ball balls bam ban banana band bands bane bang bank banks banner bar "
+        "bara bard bare barer barn barra bars bart barth baru bas base based bases bash basic "
+        "basis basket bass bat batch bate bath batis battle baud bay bea beam bean beans bear "
+        "beat beats beaut beck bed beds bee beek been beer before beg begin behind being bel "
+        "belief bell bella bells below belt ben bench bend bene beni ber bere berg berger beri "
+        "bern berry bert bes best bet beta beth bets better bhar bias bib bid bien bier big "
+        "bike bill bin binary bind binder bine bing bins bios biotic bird birds birth bis "
+        "bishop bit bite bito biz black blad blade blah blank blas blast bled blend blick blind "
+        "blink blo blob bloc block blood blower blue blur boa board boat bob bod boden body bog "
+        "bola bold bole boll bolo bolt bom bomb bon bond bone bones boni bonus boo book bool "
+        "boom boost boot boots bor bord border borg born borne boro borrow bos boss bot both "
+        "bottom bounce bound bourg bout bouw bow bower boxes boxing boy bra brace brain brains "
+        "bran branch brand bread break bred breed brew brick bridge brief brig bright bring "
+        "brit broken broker brook brot brown browse brush bubble buck bucket bud buddy budget "
+        "buds buff buffer bug build built bulk bull bullet bum bun bund bundle bung bur bureau "
+        "burg burn burst bury bus buster busy but button buy buyer buzz cab cache cad cade cake "
+        "cakes cal call caller cam came camel camera camp campo can cancel cand canner cannot "
+        "canon cant canvas cap cape car cara carbon card care career caret cargo carry cart "
+        "case cash casino cass cast caster cat catch cate cation caught cause cede cee ceil cel "
+        "cell cement cent center cep ceptor ceral ceria cern cess cha chaft chai chain chair "
+        "chal chalk champ chance chang change chant chap char charge chart chat chaus che cheap "
+        "check chee chef chen cheng chet chi chia chid chief chien chil child chin china chine "
+        "ching chip chips chlor cho choice chol choose chosen christ chrome chunk church cid "
+        "cine cion cipher circle cit cite city civil claim clam clang clare class clave clean "
+        "clear cled click client cline cling clinic clip clips clipse cloak clock clone close "
+        "closed cloth cloud club coach coal coat cobra cod code coder coe coffee cohol coil "
+        "coin col cola cold cole coli coll colon color colors column coma comb combat come "
+        "comes comic coming comma commit common con cond cone cones conn conte conto contra "
+        "cony cook cool coop cop cope copy cor cord corder core corn corner corp cos cost cot "
+        "could count county coupon cours course court cover cow cox craft cran cratch crate "
+        "crawl cream crease create credit cree creen crest crete crew crib crime cris critic "
+        "cro crop cross crow crumb cry crypt cub cube cue cult cup cur curl curr curse cursor "
+        "curve custom cut cute cyan cycle dab dad dade dae daemon dag daily dain dak dal dale "
+        "dam damage dan dance dang danger dao dap dar dark dart das dash data date dater dating "
+        "datum day days dead deal dealer death deb decess deck decode dee deep define deg "
+        "degree del delay dele delete delta deme den dene dense dent deny depart depend deploy "
+        "depth dere derive dern design desk dess detach detail detect dev device dew dha dial "
+        "dib dice did diet dig digest digit dim din ding dip dire direct dirty dis disc dish "
+        "disk dit dita ditch div divide dob doc dock docker doctor dod does dog dogs doing dol "
+        "dom domain don done dont doom door dop dor dos dose dot double dow down draft drag "
+        "dragon dram draw drawer dream dress drink drive driver drop dry dual dub duck duct "
+        "ductor duit dum dummy dump dup during dust dux each ean ear earing early earn earth "
+        "ease east easy eat ebb eben echo eddy eden edge edict edit edith editor edo educt eel "
+        "eer effect eft egg egger ego either eke eker eking eland elate elb eld elder elding "
+        "elect elf eli elia elian elite elk ell ella elle ellen elm elod elon elope els else "
+        "elt elves embar embed ember eme emit emm emma empt empty emu enable encode end ended "
+        "ender endere ending endue enemy energy engine enos ens ense ensky ensure ental enter "
+        "entity entry enzyme epoch equal equip era erade eral erase erd ere erg eria erian erie "
+        "ermine erne eros err erring error ers erse escape escort ess essay essed essie estado "
+        "estate esteem ester estre eta etch ether ethyl etna etta ettle eva eve even event ever "
+        "every evil ewer exact exam excel except exist exit expand expect expert expire expiry "
+        "export extend extent extern extra eye eyen eyer eyey eyn fabric face facet fact factor "
+        "fad fade fail fair faith fake faker fall fallen false fam family fan fang fant far "
+        "farm fass fast fat fatal father fatter fault favor fear feat fed fee feed feel feer "
+        "fei fell fels felt female fen fern fest fet fetch few fib fiber fico fid field fifo "
+        "fig fight figure file fill filled film filter fin final find finder fine finger finish "
+        "finite finity fir fire firm first fish fit five fix fixed flag flake flare flash flat "
+        "fleet flex flight flip flix flo float floor flora flow flower flu fluid flush flux fly "
+        "foam focus fod fog foil fold folder folie folio folk follow fon fond fono font foo "
+        "food foot footer for fora force forced forcer ford forest forge forget forgot fork "
+        "form formal format forme formed former formin fort forth forum fot found fox fra fram "
+        "frame fred free freeze fresh fried friend frig frist fro frog from front fruit fuel "
+        "full fully fum fun fund funk fusc fusion future gab gabe gable gad gage gain gal gam "
+        "game gaming gamma gan gang gant gaon gap gar gara garden gare garten gary gas gast gat "
+        "gata gate gau gave gaz gear ged gee gel geld gelt gem gen gender gene genic genre gens "
+        "gent geo ger gerald gers ges gest get geta getter gey gez ghan ghost gid gie gif gift "
+        "gig gil gin ging gio girl gist git give given giver giving glass glib global glyph gnu "
+        "goal god going gol gold golly gon gone gong goo good goods gor gos got gra grab grad "
+        "grade graded grader grain gram grand grant graph grass grat gratis grave gray great "
+        "gree green greg grey grid griff grim gris gross ground group grow grown growth grunt "
+        "guan guard gue guess guest guide guild guise gul gulp gum gun guna gur guru gus gust "
+        "gut gym gyro habit hack had haft hag hah hail hain hair hak hal hala hale half hall "
+        "halo halt halter halve ham hammer han hand handle hanger hao hap happy hard harm hart "
+        "hash hasta hat hau hausen have haven haw hawk hawm hay head headed header heal health "
+        "heap hear heart heat heater heavy heck heder heed heer hehe hei height hein hele hello "
+        "helm helmet help helper hem heme hen hend hep her hern hero hers het hew hex hey hia "
+        "hic hid hidden hide high higher hill him hin hind hing hint hip hire hiro his hist hit "
+        "hler hob hobo hod hog hoi hold holder hole holm holt holy home hon hone hong hood hoof "
+        "hook hoot hop hope hopper hora horn horse hose host hot hotel hound hour house hoven "
+        "hover how hub hud hug hui huk hum huma human hun hung hunt hunter hurst hurt hut hwa "
+        "hyp hyper ian iao iba iban ibid ibo ice iced ich icho icing icon icy ida ide idea "
+        "ideal idean ides idle idler ido idol ife iffy ignite ignore ihi ijo ikat ike ikey ila "
+        "ilia ilian ilium ilk ilka ill illy ilot ima image imam imber imer imi imine immi immit "
+        "immune imp impact impi import imu inca inch income ind indaba indan inde indent index "
+        "india indic indra indy ineri inermi inez infect infer inform infra ing inga inger "
+        "ingle inia inion initis inject ink inken inker inkle inks inky inn inner inning ino "
+        "inoma input insert inside insula intend intent inter intern into invent invert invest "
+        "invite invoke ion ione ioni ionic ipid ira iran irani ire iris irish irk irma iron ism "
+        "iso issue issuer ist istle ita itala itali italic itch item iten iter ither ito its "
+        "itys itza iva ivan ivin ivy iwa iyo izar izard izzard jab jack jade jam jama jaman jan "
+        "jar jara jat jati java jaw jay jed jem jest jet jete jim jin jing job joch joe john "
+        "join joint joker jon jong joni jos jours joy juan jud judge jug juice juju jump jun "
+        "junk junto jur jury just jut kai kaj kan kana kang kari karma kat kate kay kea ked kee "
+        "keen keep keeper keet kele ken kend kenn kent kep ker kern kernel ket keta key kick "
+        "kid kids kil killer kim kin kina kind king kino kip kish kiss kit kite kitty knife "
+        "know known koa kob koch kol kon kona kop kor kos kou kra kraft kreis kua kung lab "
+        "label labor lac lace lack lad lade laden lady lag lagen lager lai laid lain lak lake "
+        "lalo lam lama lambda lament lamp lan lana land lander lane lant lap lar large lari las "
+        "laser lash lass last lat late lated laten later latest latex latin lation laugh launch "
+        "lava law lay layer layout lazy lea lead leader leaf league lean lear learn lease least "
+        "leave lech leck lector led leda lede leden ledge ledged ledger lee leed leep leer lees "
+        "leet left leg legacy legal legate legend leger leges lei leigh lek lemma len lend lene "
+        "length lens lent leo ler les less lesson lest let lete lett letter lev levant level "
+        "lever lew lex lexia ley liable lias lice lich lichen licit lick lid lide lie lied lief "
+        "lier lif life lift light ligne like lim lime limit lin line linear lined linen liner "
+        "ling linge linger linha linie lining link linked links linky lint lion lip lis lish "
+        "list listed listen lit lite liter little liv live living liz loa load loaded loader "
+        "loan lob lobal local locale loch lock locked locker lod lof log loge logged logger "
+        "logic login logo logos loin loir long loo lood look lookup loom loon loop loot lop "
+        "lope lord lose loss lost lot lots lotte lou love lover low lower lox loyd luc luck lug "
+        "lum lunes lung lur lush lut lux lying lys lysis mac mack macro mad made mag mage magic "
+        "mah mail mailer main maine maint major make maker making mal malar mall mallow mam man "
+        "mana manage mand mande manent manes mani mania mann mano mans manse mant manual manuel "
+        "many mao map mapper mar march mare margin marine mark marked marker market markup mars "
+        "mart marvin mary mas masa mask masked mass massa mast master mat match mate mater math "
+        "matrix matter max may maya maybe maze meal mean mede media median medio medium meet "
+        "meg mein mel meld mele melon mem member memo memory men meng ment mental mentor menu "
+        "mer mere merge merk mero mes mesa mese mesh mess messe messer mester met meta metal "
+        "mete meteor meter method metic metric mica mico micro mid middle mien mig might mil "
+        "mile milk mill mime min mina mind mine miner ming mino minor mint minus minute mir "
+        "mirror mise miss mist mite mitt mix mixed mob mobile mock mod modal mode model modern "
+        "modify module mog moil moire moment mon money mong mongo mono mont month monton moo "
+        "moon moor mooth mor more morgen mort most mostly mot mother motion motor mount mouse "
+        "mouth move movie moving mrs much mud mult mum mun mund mung munity mus museum music "
+        "must mute mux naa naam nab nable nach nae nag naio nais nak nam nama name nan nance "
+        "nancy nant nap nar nard nast nat nation native nature nay nea neal near neath neb neck "
+        "ned nee need needle needs neet nef nei nell nelly neo ness nest nesty net nete never "
+        "new news next nias nice nici nick nid night nil nim nine ning nisse nit nod node nog "
+        "noise noma nome non nonce none noop nor norm normal north nose nostic not note notice "
+        "notify nou noun nous nova novo now nth nub nul null number numero nun nut nye oak oban "
+        "obe obi object occur och ock ocracy ocular oda odal odd ode odel odin odium odor ods "
+        "odz oes off offer office offset oft often ogle ohia oil oint oka okee oki okia okra "
+        "old olden older ole oleg olid olio olive olla olm ology olor olson oman omar omber "
+        "omega omen omer omina omit ona once one oner onium only ons ontal onto onus onym onza "
+        "oodles oons oord opal opaque ope open opera opsy opt optic option opus ora oracle "
+        "orage orang orange orb orbit orc orca order ordu ore orf organ orgia orias orient "
+        "origin orna orris ort ory osc ose ossal osse ostic otate other otic otis oto otto otus "
+        "ouch ouf ough ought ounce ounds ours oust out outed outen outer outing output ova oval "
+        "oven over ovine ovis owe ower owing owl owler own owner oxide oxy oxygen oyer paar pac "
+        "pace paced pack packer packet pad page pager pagina pail pain paint pair paired pais "
+        "pal pam pan pand panel pang panic pant pants pap paper paque par para param parate "
+        "parcel pard paren parent parer pari paring park parse parser part party pass passen "
+        "past paste pat patch path pathy pau pause paw pawn pay payer pea peace peak peaker "
+        "peat ped peed peer peg pele pell pen pend pent people pep per peri period perk perm "
+        "permit person pert perty pes peso pet phase phasis phi phil pho phon phone phonic "
+        "phony phot photo phrase pia pic pick picked picker pickle pie pier pig pik pile pill "
+        "pillar pilot pin pine ping pink pip pipe pir piro pit pitch pivot pix pizza place "
+        "placer plain plan planet plant plash plass plat plate play player please pled plex "
+        "pliant plied plier pliers plies plot ploy pluck plug plural plus ply pod poi point "
+        "poke pol polar pole policy polis poly pom pon pond ponder pone ponent pong pont pony "
+        "pool poor pop poral port porta portal ported porter porto pose poser posing posit poss "
+        "post postal posted poster pot pow power pox pray prefer prefix prep preset press prest "
+        "pretty price priced prim prima prime primer print prior pro prob probe prod prof "
+        "profit prog prompt proof prop proper props prote proto prove proved prow proxy pseudo "
+        "psi pst psych puan pub public pul pull pulse pump pun punt pur pure purple puru push "
+        "put python qua quad quake quan quant quare quart quat queen query quest quet queue "
+        "quick quid quiet quila quin quina quip quire quis quit quite quiz quo quot quota quote "
+        "raad rab rabbit race rach rack rad rada radio radius raff raft rag rage rah raid rail "
+        "rain rais raise raised raiser raj rale ram rama rame ran rana rance rand random rang "
+        "range rank rant rap rapid rapper rare ras rase rash rat rate rated rather rating ratio "
+        "ration raul raw rax ray rea reach react read reader ready reak real really realm ream "
+        "rear reason reb recent recipe reck record rect red redd rede redo reduce redux ree "
+        "reef reek reem reen rees reet ref refer refix refund reg region reh rein reis reit "
+        "reject rel reland relay reload remain reman remark remote remove renal rename rend "
+        "render renew rent rep repair repeat repen reply report resent reset resh resize resp "
+        "rest result resume ret retain retan retch retry return reuse rev reve revet review "
+        "reward rex rhein rho ria rial rib ric rice rich richt rick rid ridden ride ridge rie "
+        "rier riff rift rig right rik rim rine ring ringer rink rio riot rip rise risk rist rit "
+        "rita rite rive river rix roach road rob robe robot roc rock rocket rod rodd roe rog "
+        "roger roi roit rok roke roker role rolled roller rolley roman rome ron rone rong roof "
+        "rook room roon root rope ropy rosa rose ross rot rota rotate rote rottle roud rough "
+        "round roup route router rove row rowing rox roy rub ruby ruck rud ruff rug rule rum "
+        "run runner rupa rus rush rust rut ruta sab sad safe sage said sak sal salary sale salt "
+        "sam same sample san sand sans sap sar sass sat save saved saving say scala scalar "
+        "scale scaled scan scape scar scene schema scheme school schule scient scious scope "
+        "score screen scribe script scroll sea seal sealed search season seat sec second secret "
+        "sect sector secure seed seeing seek seen seer seg segue seid seit sele select self "
+        "seller semble semi sen send sender sense sensor sept ser sera seri serial series sero "
+        "sert serve server servo sess set sett setter setup seven sey sha shade shader shadow "
+        "shake shall shan shape share sharp shaw shay she shed sheet shell shen sheng shi "
+        "shield shift shim shin shine ship shire shirt shiv sho shock shoe shop shore short "
+        "shot should show shown shu sia sib sic sid side sie sig sigma sign signal sil silent "
+        "silver sim simple sin since sing single sink sip sir sis sit six size sizes skal skat "
+        "sker ski skill skim skin skip sky sla slam slash sled sleep slice slick slide slider "
+        "slot slow slug small smart smarty smith smooth snake snap snow soap sob soc social "
+        "sock socket soe soever soft soil sol solar sold sole solid solo solute solve solver "
+        "some son song sons soon sorry sort sorted sou sound source south soy spa space spam "
+        "span spann spar spark spart spawn spec sped speech speed spell spent sphere spiel "
+        "spill spin spire spired splice split spoken spor sport sports spot spread spring "
+        "sprite spur spy square ssi stable stack staff stag stage stake stall stamp stan stance "
+        "stand star start stash state static status staw stay stead steady steam steel steen "
+        "stein stell stem sten step stern stick sticks sticky stid still stim stime sting stock "
+        "stocks stod stof stoff stone stood stop store storm story stra stract strain strand "
+        "strap stre stream street streng stress strict stride strike string strip stripe strix "
+        "stroke strom strong stu stub stud studio study stuff stum sty style sub submit subset "
+        "such suffix suite summer sup super sur sure surf survey sus swap sweet swift swiper "
+        "switch symbol sync syntax system taa tab tabla table tables tablet tach tag tai tail "
+        "tain taj take taken taking tal talk tam tan tank tap tar tara tare target task taste "
+        "tat tau tax tay tea teach team tear tec tech ted tee teen teg teil tele tell tema temp "
+        "temper tempo tempt ten tenant tensor tent tera teras teri term termin tern terna "
+        "ternal terne test teste tested tester text tez tha thai than thane thank thanks that "
+        "the their them theme then these theta they thin thing think third this tho thon thorn "
+        "those though thouse thread three throw thumb thus thy tic tick ticker ticket tid tie "
+        "tier tig tight til tile tim time timer times tin ting tiny tip title titre toa toast "
+        "tod today toe tog toggle toi token tol tom ton tone tong too tool toon top topia topic "
+        "tops tor torch tot total tou touch tour tout tower town tox toy tra trace track tract "
+        "trade trag trail train trait tram tran trap trash travel tray tree trend trent tri "
+        "trial trica trim trin trip tron truck true trust truth try trying tube tum tun tur "
+        "turn turned tweet twig two type uang ubi uca udal udder udi udo uds ugh uji uke ula "
+        "ule ull ulla uller ulling ultima ultimo ulu umber umble umbo ume ump umph umu una "
+        "unable unal unami unbind unca uncate unci uncia unde unden under undo undy unie union "
+        "unique unit unity unken unless unlink unlock unsafe unset untar until unto unused "
+        "unwrap unze update upload upo upon upper ura ural uran urate urban urd urde urdu ure "
+        "urent urf urge urgent urger uri uria urlar urn urna urnal urning uro urs ursa ursal "
+        "ursus uru urus usable usage usar use used user ush usher ussels ust uster usual usun "
+        "uta utas utch ute utile utter utu utum uva vai vain vair val vale vali valid vall "
+        "valor value valuer van vang vara vare vari varna vary vas vast vat vault veal vector "
+        "veda vedic vee veen veer vei veil vela vell velo velte vend vendor vent venter venue "
+        "venus vera verb verd verify verity vern versal verse versed verst vert vertex very "
+        "vest vester vet via vic vice video vie vier view viewer vill villa ville vim vina "
+        "vince vine vino viol vip vira viral viron virus vis visa vise vision visit visor vista "
+        "visual vita vive vod voet vog voice void vol vole volent volt volume vote vum waar wab "
+        "wad wadi wag wagon wah wain wait waka wake wale wali walk walker wall wallet wan wand "
+        "wander wandle wane wang want wany wap war ward warden ware warf warm warn warp wart "
+        "was wash washed washer wat watch water wave wax way wayne ways weak wealth weapon wear "
+        "web wed wee weekly ween weep weet wei weka well welt wem wen wend went"
+    ).split()
+)

id_agent/py.typed

@@ -0,0 +1 @@
+

id_agent-1.1.3.dist-info/METADATA

@@ -0,0 +1,527 @@
+Metadata-Version: 2.4
+Name: id-agent
+Version: 1.1.3
+Summary: Human-readable, token-efficient IDs for AI agent systems
+Project-URL: Homepage, https://github.com/vostride/id-agent#readme
+Project-URL: Repository, https://github.com/vostride/id-agent
+Project-URL: Issues, https://github.com/vostride/id-agent/issues
+Author: Vostride
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,collision-resistant,human-readable,id,identifier,llm,token-efficient,uuid-alternative
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/vostride/id-agent/main/docs/id-agent.png" alt="id-agent - Token efficient IDs for AI agents" />
+
+  [![Featured on Hacker News](https://img.shields.io/badge/Hacker%20News-featured-ff6600?style=flat&logo=ycombinator&logoColor=white&colorA=13110f)](https://news.ycombinator.com/item?id=48191852)
+  [![npm](https://img.shields.io/npm/dm/id-agent?style=flat&colorA=13110f&colorB=196872)](https://npm.chart.dev/id-agent?primary=neutral&gray=neutral&theme=dark)
+  [![npm version](https://img.shields.io/npm/v/id-agent.svg?style=flat&colorA=13110f&colorB=196872)](https://www.npmjs.com/package/id-agent)
+  [![GitHub stars](https://img.shields.io/github/stars/vostride/id-agent?style=flat&colorA=13110f&colorB=196872)](https://github.com/vostride/id-agent/stargazers)
+
+  <p>
+    <a href="#the-math">The Math</a>
+    ·
+    <a href="#javascript--typescript">JavaScript</a>
+    ·
+    <a href="#python">Python</a>
+    ·
+    <a href="https://www.npmjs.com/package/id-agent">npm</a>
+    ·
+    <a href="https://vostride.com">Vostride AI</a>
+  </p>
+</div>
+
+# 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
+
+| Format | Example | Tokens (o200k_base) | Collision Resistance |
+|--------|---------|---------------------|----------------------|
+| UUID v4 | `89b842d9-6df9-4cf4-8db0-9dc3aed3cfd7` | about 23 | 122 bits |
+| id-agent (default, 8 words) | `urd-antes-sorry-pac-dire-total-expire-going` | about 14 | about 96 bits |
+| id-agent (5 words) | `frame-beer-bell-tog-hoot` | about 8 | about 60 bits |
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="docs/id-agent-tokenizer.png" alt="id-agent: 12 tokens for 8 words" width="100%" /><br/><strong>id-agent</strong> - 8 words, 43 chars, <strong>12 tokens</strong></td>
+    <td align="center"><img src="docs/uuid-tokenizer.png" alt="UUID v4: 26 tokens" width="100%" /><br/><strong>UUID v4</strong> - 36 chars, <strong>26 tokens</strong></td>
+  </tr>
+</table>
+
+### Entropy
+
+Each word is drawn uniformly from a curated **4096-word list** (2^12). Every position in the ID is an independent random selection:
+
+```text
+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:
+
+```text
+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).
+
+| Words | Bits | ID Space | P @ 1K | P @ 10K | P @ 100K | P @ 1M | P @ 1B | 50% collision at |
+|-------|------|----------|--------|---------|----------|--------|--------|------------------|
+| 3 | 36 | 6.9 * 10^10 | 7.3 * 10^-6 | 7.3 * 10^-4 | 7.3 * 10^-2 | about 1 | about 1 | about 309K items |
+| 4 | 48 | 2.8 * 10^14 | 1.8 * 10^-9 | 1.8 * 10^-7 | 1.8 * 10^-5 | 1.8 * 10^-3 | about 1 | about 20M items |
+| 5 | 60 | 1.2 * 10^18 | 4.3 * 10^-13 | 4.3 * 10^-11 | 4.3 * 10^-9 | 4.3 * 10^-7 | 0.43 | about 1.3B items |
+| **8** | **96** | **7.9 * 10^28** | **6.3 * 10^-24** | **6.3 * 10^-22** | **6.3 * 10^-20** | **6.3 * 10^-18** | **6.3 * 10^-12** | **about 331T items** |
+| 10 | 120 | 1.3 * 10^36 | 3.8 * 10^-31 | 3.8 * 10^-29 | 3.8 * 10^-27 | 3.8 * 10^-25 | 3.8 * 10^-19 | about 1.4 * 10^18 items |
+| *UUID v4* | *122* | *5.3 * 10^36* | *9.4 * 10^-32* | *9.4 * 10^-30* | *9.4 * 10^-28* | *9.4 * 10^-26* | *9.4 * 10^-20* | *about 2.7 * 10^18 items* |
+
+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:
+
+```text
+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:
+
+| Format | Avg Tokens | Entropy | Tokens Saved vs UUID | Savings |
+|--------|------------|---------|----------------------|---------|
+| UUID v4 | **about 23** | 122 bits | -- | -- |
+| id-agent (3 words) | **about 5** | 36 bits | about 18 | **78%** |
+| id-agent (5 words) | **about 8** | 60 bits | about 15 | **65%** |
+| **id-agent (8 words, default)** | **about 14** | **96 bits** | **about 9** | **39%** |
+| id-agent (10 words) | **about 17** | 120 bits | about 6 | **26%** |
+
+### Choosing Word Count
+
+The right word count depends on your scale. The default of 8 is deliberately conservative and globally safe.
+
+| Scale | Recommended | Entropy | Why |
+|-------|-------------|---------|-----|
+| Dev/testing | `words: 3` | 36 bits | Fast, memorable, about 5 tokens. Collides at about 300K items. |
+| Team tools | `words: 4` | 48 bits | Safe to about 20M items. Good for internal APIs. |
+| Production SaaS | `words: 5` | 60 bits | Safe to about 1B items. 65% token savings vs UUID. |
+| High-volume / distributed | `words: 8` (default) | 96 bits | Safe to about 300T items. The safe default. |
+| UUID-equivalent | `words: 10` | 120 bits | Matches UUID v4 collision math. |
+
+### 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:
+
+```text
+"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](#javascript--typescript)
+- [Python](#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
+
+```bash
+npm install id-agent
+```
+
+```bash
+pnpm add id-agent
+```
+
+### Quick Start
+
+```typescript
+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.
+
+```typescript
+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:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | `undefined` | Type prefix, lowercase alphanumeric only |
+| `words` | `number` | `8` | Number of words, 1-16. Controls entropy: words * 12 bits |
+
+### Deterministic IDs
+
+Generate a deterministic ID from a string input using HMAC-SHA256. The same input always produces the same ID.
+
+```typescript
+import { idAgent } from 'id-agent'
+
+const id = await idAgent.from('user@example.com')
+
+const namespaced = await idAgent.from('user@example.com', {
+  namespace: 'my-app',
+  prefix: 'user',
+  words: 5,
+})
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | `undefined` | Type prefix, lowercase alphanumeric only |
+| `words` | `number` | `8` | Number of words, 1-16 |
+| `namespace` | `string` | `'id-agent'` | HMAC key for domain separation |
+
+### Parse
+
+Parse any id-agent ID into its components. Supports hyphen-separated and underscore-separated words. Returns `null` for unrecognized formats.
+
+```typescript
+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`.
+
+```typescript
+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.
+
+```typescript
+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:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `words` | `number` | Yes | Number of words per alias, 1-16 |
+
+### Duplicate Detection
+
+Scan text for duplicate IDs using a regex pattern. This is a pure function with no filesystem access.
+
+```typescript
+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:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `pattern` | `RegExp` | Regex to match IDs in text |
+| `text` | `string \| string[]` | Text to scan for duplicates |
+
+### 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.
+
+```typescript
+import { WORDLIST } from 'id-agent'
+
+WORDLIST.length           // => 4096
+Object.isFrozen(WORDLIST) // => true
+```
+
+## Python
+
+### Install
+
+```bash
+pip install id-agent
+```
+
+```bash
+uv add id-agent
+```
+
+### Quick Start
+
+```python
+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.
+
+```python
+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:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `str \| None` | `None` | Type prefix, lowercase alphanumeric only |
+| `words` | `int` | `8` | Number of words, 1-16. Controls entropy: words * 12 bits |
+
+### Deterministic IDs
+
+Generate a deterministic ID from a string input using HMAC-SHA256. The same input always produces the same ID.
+
+```python
+from id_agent import generate_deterministic
+
+id = generate_deterministic("user@example.com")
+
+namespaced = generate_deterministic(
+    "user@example.com",
+    namespace="my-app",
+    prefix="user",
+    words=5,
+)
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `str \| None` | `None` | Type prefix, lowercase alphanumeric only |
+| `words` | `int` | `8` | Number of words, 1-16 |
+| `namespace` | `str` | `"id-agent"` | HMAC key for domain separation |
+
+### Parse
+
+Parse any id-agent ID into its components. Supports hyphen-separated and underscore-separated words. Returns `None` for unrecognized formats.
+
+```python
+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`.
+
+```python
+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.
+
+```python
+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:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `words` | `int` | Yes | Number of words per alias, 1-16 |
+
+### Duplicate Detection
+
+Scan text for duplicate IDs using a regex pattern. This is a pure function with no filesystem access.
+
+```python
+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:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `pattern` | `str \| re.Pattern[str]` | Regex to match IDs in text |
+| `text` | `str \| Iterable[str]` | Text to scan for duplicates |
+
+### 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.
+
+```python
+from id_agent import WORDLIST
+
+len(WORDLIST)                 # => 4096
+isinstance(WORDLIST, tuple)   # => True
+```
+
+## License
+
+MIT

id_agent-1.1.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+id_agent/__init__.py,sha256=EswACnwwV1bcjrBX48b-rnW6s6WssSVawjcYJAVDPcQ,502
+id_agent/_alias.py,sha256=xKrNPGSQqNVjw-wxKeB66aqUFxAClEdmKY4evhvjqG8,2941
+id_agent/_detect.py,sha256=mM7v0xUyDOkyfElUSBJWA_X-AlRp33YDXSJpfUnIZ54,1447
+id_agent/_generate.py,sha256=mS2YOnHTYzZLJFt6VcPFsa26dwJ3teZ8dvjonrv766A,2375
+id_agent/_parse.py,sha256=UHcsO8yOm3b1bPhcbmACrCSCwGOCt9128_mdN7tr3rQ,1915
+id_agent/_types.py,sha256=2N00hZj-AyExvN5E19IZvhXZaCkZuVVbVJhgAWwRYfo,578
+id_agent/_wordlist.py,sha256=ZQFrD2JWREh5dn2B2NYT79L9T3ZWjz3omjgGo-oj-cY,24806
+id_agent/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+id_agent-1.1.3.dist-info/METADATA,sha256=UT-QECLtyAmpfP9trBGnZgmwyoMl-wkL8zveZbZq8F0,18100
+id_agent-1.1.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+id_agent-1.1.3.dist-info/licenses/LICENSE,sha256=urCS6Lg0qwsNOG8gceeLh6Yx92oTgG5QxD4laIjocZ4,1078
+id_agent-1.1.3.dist-info/RECORD,,

id_agent-1.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

id_agent-1.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 id-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.