Metadata-Version: 2.4
Name: id-phrase
Version: 0.0.2
Summary: A simple utility to generate unique, human-readable identifiers.
Project-URL: Homepage, https://github.com/afourney/id-phrase
Project-URL: Repository, https://github.com/afourney/id-phrase
Author-email: Adam Fourney <adam.fourney@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Adam Fourney
        
        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.
License-File: LICENSE
Keywords: human-readable,id,identifier,phrase,session-id,slug,uuid
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# id-phrase

Generate human-readable, LLM-friendly identifier phrases like `sharp-spirited-existence-052e`.

## Installation

```bash
pip install id-phrase
```

Or from source:

```bash
git clone https://github.com/afourney/id-phrase
cd id-phrase
uv venv --python python3.11
source venv/bin/activate
uv sync --all-extras
```

## Usage

```python
from id_phrase import generate_id_phrase

print(generate_id_phrase())
# → sharp-spirited-existence-052e

# Override the template:
print(generate_id_phrase("A-N-B"))
# → sharp-existence-a3

# Or supply a list — one is chosen uniformly at random per call:
print(generate_id_phrase(["A-A-N", "A-V-N"]))
```

## Why?

LLMs struggle to accurately copy high-entropy strings like UUIDs and hex identifiers. When asked to reference or reproduce an identifier like `a90d0d7d-9c5a-44de-8d3c-5b0da661de7c`, models make typos, truncate values, or hallucinate entirely different IDs.

The root cause is tokenization: a UUID consumes ~23 tokens because hex characters and hyphens don't align with the natural language patterns tokenizers are optimized for. Word-based identifiers, by contrast, are tokenized as whole familiar words, making them far more reliably reproduced.

This library generates identifiers in the style of `sharp-spirited-existence-052e` — a short random hex suffix for uniqueness, combined with natural English words that LLMs handle well.

### The evidence

- **BAML Blog — [Using UUIDs in prompts is bad](https://boundaryml.com/blog/uuid-swap)** (Oct 2025): Benchmarked Claude Haiku on aggregation tasks with 200 items across 100 class IDs. The UUID approach produced 29–68 errors per run; the integer-remapped approach produced only 5–7 errors. Opus 4 reached 100% accuracy with integer IDs but only 80% with UUIDs.
- **Nikhil Verma — [LLMs as Unreliable Narrators: Dealing with UUID Hallucination](https://nikhil-verma.com/blog/llms-unreliable-narrators-uuid-hallucination/)** (Nov 2025): Recommends using human-readable identifiers like titles instead of UUIDs in enums, noting that "UUIDs are harder for models to reproduce accurately because they're random. Titles are memorable patterns." Also available on [DEV Community](https://dev.to/nikhilverma/llms-as-unreliable-narrators-dealing-with-uuid-hallucination-151e).
- **Floris Fok — [The Hidden Cost of UUIDs in AI Prompts](https://medium.com/prosus-ai-tech-blog/the-hidden-cost-of-uuids-in-ai-prompts-a-95-6-token-optimization-solution)** (Prosus AI Tech Blog): Shows that a single UUID consumes ~23 tokens due to tokenizer inefficiency with hex strings and hyphens, and demonstrates up to 95.6% token reduction by replacing UUIDs with compact identifiers.

The common recommendation across all three sources is the same: if you can avoid giving the model a UUID, do so. `id-phrase` lets you generate identifiers that are unique enough for practical use and reliable enough for LLMs to work with accurately.

## Templates

`generate_id_phrase()` accepts a template string (or a list of templates to pick from at random). Each letter in the template expands to a random component; any other character is kept verbatim as a separator.

| Letter | Expands to                                         |
| ------ | -------------------------------------------------- |
| `A`    | a random adjective (e.g. `corporate`)              |
| `V`    | a random verb — present participle (e.g. `asking`) |
| `N`    | a random noun (e.g. `poetry`)                      |
| `B`    | a random byte as two hex digits (`00`–`ff`)        |

So `A-A-N-BB` expands to `{adjective}-{adjective}-{noun}-{hex4}` — e.g. `sharp-spirited-existence-052e`. Use multiple `B`s back-to-back to widen the hex suffix (`BB` = 4 hex chars / 2 bytes, `BBB` = 6, etc.).

The default is `["A-A-N-BB", "A-V-N-BB"]`: one of the two is chosen uniformly at random per call, which roughly doubles the phrase space at no readability cost. The hex suffix adds uniqueness guarantees while keeping the human-readable words as the primary identifier the LLM interacts with.

## License

MIT
